Immersion Web Plugin Reference

Immersion Web Plugin Reference

This document covers the Immersion Web Plugin Version 3.2.2.1. Look at the What's New page.

The Immersion Web Plugin allows TouchSense technology to be experienced within Web pages. In Microsoft Internet Explorer, the browser plugin is the Immersion Web ActiveX Control. The control makes much of the Immersion Foundation Classes (IFC) functionality available within Internet Explorer (or Visual Basic, Microsoft Excel, and other ActiveX control containers). In Netscape Navigator, the browser plugin is the Immersion Web Netscape Plugin. This Netscape plugin makes use of the underlying ActiveX control. Both the Immersion Web ActiveX Control and the Immersion Web Netscape Plugin will be generically referred to as the "Immersion Web Plugin" for the remainder of this document, unless a more specific reference is necessary.

Using the Immersion Web Plugin, JavaScript in web pages is allowed to communicate with a force-feedback pointing device such as the Logitech iFeel Mouse. In addition, the Immersion Web Plugin also supports all existing DirectX force-feedback joysticks, steering wheels, and gamepads.

This reference documents the public methods of the Immersion Web Plugin. These methods are callable through JavaScript within a Web page. This reference also describes the Plugin's supported effects and how to manipulate them.

For more technical specifications, please refer to the IFC Reference documentation, available for download from the documentation or SDK pages at http://www.immersion.com/developer/.

Follow one of these links to begin:

Effects Supported by the Immersion Web Plugin

Methods of the Immersion Web Plugin

  • Managing Devices
  • Making Effects
  • Playing and Managing Effects
  • Changing Effect Properties
  • Getting Effect Properties
  • Examining Version Information

Using TouchSense Gaming Devices with the Immersion Web Plugin

Detecting the Immersion Web Plugin on a User's System

Notes for C/C++ Developers

More Useful Tips on Working with the Plugin

Please send all questions and feedback to developer@immersion.com.


What's New With The Immersion Web Plugin

The current version of the Immersion Web Plugin is 3.2.2.1.

This is a minor update to the Immersion Web Plugin.

If you have any comments, suggestions, bugs, or general feedback, email developer@immersion.com.

Changes Between 3.2.2.1 and 3.2.2.0

  • Upgraded to use IFC 2.2, version 2.2.6
  • Fixed ChangeInsideEffect to work properly
  • Will work with I.E. 5.5 to handle relative file paths for IFR files

    Changes Between 3.2.2.0 and 3.2.1.2

  • Supports TouchSense-enabled DirectX devices.
  • Upgraded to use IFC 2.2, which enabled these other feature enhancements...
  • Improved device detection, allowing you to query device name, type, and technology.
  • There are now Get Property methods for all of the properties.
  • Added more fine-grained effect manipulation. You may now query and alter positive-X, positive-Y, negative-X, and negative-Y directions of may properties.
  • Added MakeGrid2 method to allow the creation of directional grids.
  • Added methods for retreiving the version numbers of various installed Immersion technologies (GetPluginVersion, etc.).
  • Added methods for querying the capabilities and existence of effects (EffectSupportsChange, EffectSupportsGet, EffectExists, GetNumberOfEffects, GetNameOfEffect).
  • You can now query compound effects for their primitive effects (GetNumberOfEffectsInCompound, GetNameOfEffectInCompound).
  • Added method for querying mouse cursor position (GetCursorPosX, GetCursorPosY).

    Changes Between 3.2.1.2 and 3.2.1.1

  • Fixed random Netscape crashing.

    Changes Between 3.2.1.1 and 3.2.1.0

  • Dramatically improved child window support in Netscape Plugin.
  • Netscape Plugin was missing the MakePeriodic2 method.

    Changes Between 3.2.1.0 and 3.2.0.4

  • Added support for all TouchSense-enabled DirectX devices (joysticks, steering wheels, etc.).
  • Updated to use IFC 2.1.
  • Eliminated dependency on MFC, reducing the download size by 610k and eliminating the need to reboot after installation.
  • Better behavior with multiple browser windows (requires driver update for best results).
  • The device position, in both screen and device coordinates, can be queried.
  • Periodics with waveforms other than sinewave can now be made using MakePeriodic2.
  • Made numerous optimizations and bug fixes.
  • Fixed the "Netscape continuous streaming problem" wherein the Netscape logo would animate continually and it would never finish the page download.
  • Improved support for hosting the ActiveX Control in containers other than Internet Explorer and Netscape.
  • Improved the usability of ChangeDuration and StartEffect2 by allowing negative numbers to be used in lieu of the obfuscated 0xFFFFFFFF.
  • Improved reference documentation.
  • Added new methods:
      • GetDeviceFlag
      • GetDevicePosX
      • GetDevicePosY
      • GetLastError
      • GetNameOfEffect
      • GetNumberOfEffects
      • GetScreenPosX
      • GetScreenPosY
      • MakePeriodic2
  • Added new properties (ActiveX Control only):
      • DeviceFlag
      • LastError


Using TouchSense Gaming Devices

Immersion Web Plugin Reference

Using TouchSense Gaming Devices with the Immersion Web Plugin

As of version 3.2.1.0 of the Immersion Web Plugin, TouchSense gaming device can be used within a web page. Any TouchSense gaming device, such as a joystick, steering wheel, gamepad, or mouse that works with Microsoft's DirectX will work with the Immersion Web Plugin. A list of Immersion partners that manufacture these products is available at Immersion's web site.

Enabling TouchSense Gaming Device Support In Web Pages

By default, TouchSense gaming device support is disabled. The reason for this is that effects designed for TouchSense pointing devices often do not feel similar on TouchSense gaming devices, and vice versa. In order to ensure a consistent user experience, the default Plugin mode is to only allow TouchSense pointing devices.

Enabling TouchSense gaming device support is a simple matter of setting the DeviceFlag property of the Immersion Web Plugin. In Internet Explorer, it can be set via the <PARAM> tag inside the <OBJECT> tag. In Netscape, it can be set inside the <EMBED> tag. Also remember that the plugin version must be 3.2.1.0 or greater. The following HTML code fragments illustrate this:

Internet Explorer:
<OBJECT
    classid="CLSID:5CA42785-ABC3-11d2-9F81-00104B2225C5"
    codebase="#version=3,2,2,1"
    id="ImmWeb"
    height="0" width="0">
<PARAM name="DeviceFlag" value="2">
</OBJECT>
Netscape Navigator:
<EMBED
    type="application/x-Immersion-Web-Plugin"
    name="ImmWeb"
    hidden="true"
    src="myfile.txt"
    DeviceFlag="2">

The value of the DeviceFlag dictates how the Immersion Web Plugin will search for a device to acquire. There are currently four device flags, each named with respect to how it deals with DirectX devices (which are subset of Immersion TouchSense-enabled gaming devices). The following table, taken from the GetDeviceFlag documentation, describes each of these flags:

Name | Value | Meaning
dfForbidDXDevice | 0 | The Plugin can only acquire a TouchSense mouse.
dfAllowDXDevice | 1 | The Plugin can acquire a TouchSense mouse or DirectX device, but will look for a TouchSense mouse first.
dfPreferDXDevice | 2 | The Plugin can acquire a TouchSense mouse or DirectX device, but will look for a DirectX device first.
dfRequireDXDevice | 3 | The Plugin can only acquire a DirectX device.

In Internet Explorer and Netscape, you must use the DeviceFlag value. The DeviceFlag name can only be used by certain applications, such as Microsoft Visual Basic and Macromedia Director.

The default DeviceFlag is dfFordbidDXDevice (0). The DeviceFlag value can be retrieved using GetDeviceFlag. To check if device acquisition was successful, use TouchSenseDeviceAttached.

Known Limitations

The DeviceFlag Is Read-Only, Except During Design-Time

The DeviceFlag is a read-only property. Trying to set it using JavaScript or any other scripting language will result in an error.

The only exception to this read-only restriction occurs during design-time. Some tools, such as Microsoft Visual Basic, allow developers to manipulate objects in a design environment. Objects being used in this environment are said to be in design-time mode. Since the Immersion Web Plugin is not actively being used in design-time mode, it allows its DeviceFlag to be set. This design-time setting usually dictates what the eventual run-time setting will be.

Behavior With the Logitech Wingman Force-Feedback Mouse

The Logitech Wingman Force-Feedback Mouse (LWFFM) is interesting because it is both a TouchSense pointing device and a TouchSense gaming device. If a LWFFM is attached to the system, it will be acquired regardless of the DeviceFlag. It has a higher priority than all other devices. If the DeviceFlag is dfPreferDXDevice or dfRequireDXDevice, the LWFFM will be acquired as a joystick. To properly use the device, the user must usually manually change the LWFFM mode to Joystick using CTRL-F12. This is a standard procedure that most LWFFM owners are aware of.


Immersion Web Plugin Detection and Download

Immersion Corporation brings the sense of touch to the web through browser plugins. In Microsoft's Internet Explorer browser (version 4 and higher), the Immersion Web ActiveX Control allows communication between JavaScript in a web page and a force feedback pointing device such as Logitech's Wingman Force Feedback Mouse. In Netscape's Navigator browser (version 4.5 and higher), this communication is facilitated via the Immersion Web Netscape Plugin. Both of these plugins will be referred to below as the "Immersion Web Plugin" or "ImmWeb."

When a web page with touch sensations is designed, an object reference to either the Internet Explorer or Netscape Navigator version of the Immersion Web Plugin must be included in the page HTML. This object reference gives the JavaScript in the page access to and control over the force feedback pointing device with which a user will experience the touch sensations on the page.

An HTML object reference supporting both IE and Netscape browsers looks like this:

<OBJECT
    classid="CLSID:5CA42785-ABC3-11d2-9F81-00104B2225C5"
    codebase="#version=3,2,2,1"
    id="ImmWeb"
    height="0" width="0">
  <EMBED type="application/x-Immersion-Web-Plugin"
      name="ImmWeb" hidden="true" src="myfile.txt">
</OBJECT>
Given the object reference above, a method of the Immersion Web Plugin is called from within JavaScript as follows:
document.ImmWeb.<MethodName>(<arguments>)
If the Immersion Web Plugin for the browser type being used is installed and registered on the user's computer, the HTML object reference to the plugin, combined with the call to a method of the plugin, will allow the web page to communicate properly with the touch-enabled pointing device being used to navigate the page.

If the Immersion Web Plugin for the browser being used is NOT installed and registered on the user's computer, potentially disruptive JavaScript or Runtime error messages will appear whenever a call to the Plugin's methods is made, notifying the user that the "ImmWeb" object does not exist.

To provide the smoothest and most pleasant web page experience to users, it is important to deal gracefully with the following possible user situations:
  • the user does not have a sufficient operating system to utilize a touch-enabled pointing device
  • the user is not running a sufficient browser version to correctly install and run the Immersion Web Plugin
  • the user is running appropriate versions of both operating system and browser, but does not have the Immersion Web Plugin installed on his/her computer
  • the user has the Immersion Web Plugin correctly installed and registered on his/her computer

In the first two situations, it is important to disable any scripting within a web page which calls methods of the Immersion Web Plugin and activates touch sensations. The user will not be able to feel the touch sensations on the web page anyway, and with ImmWeb scripting disabled, will not be subjected to any distracting recurring error messages. The page designer may wish to notify a user in the first two categories that the page could be experienced much more richly if the user upgrades either the operating system or browser software (as appropriate) and browses the page with a touch-enabled pointing device.

In the third situation, when the system is sufficient but the Immersion Web Plugin is not installed, the user should be given the option to install it. If the user refuses to install the plugin, an option should also exist to suppress further offers to install. If the plugin is not installed and installation refused, touch sensations on the web page must be disabled, as for users with insufficient systems.

If the Immersion Web Plugin is correctly installed and registered, touch sensations should be seamlessly turned on without any action required of the user.

To correctly handle any of the situations above, it is first important to identify which situation exists. JavaScript statements can be written to identify both the operating system and the browser type and version being used to view the web page:

var imm_isIE = (navigator.appName == "Microsoft Internet Explorer");
var imm_isNN = (navigator.appName == "Netscape");
var imm_isIE4plus = imm_isIE && (parseInt(navigator.appVersion) >= 4);
var imm_isNN45plus = imm_isNN && (parseFloat(navigator.appVersion) >= 4.5);
var imm_isNN6plus = imm_isNN && (parseFloat(navigator.appVersion) >= 5);
var imm_usrAgt = navigator.userAgent.toLowerCase();
var imm_isWin98 = (imm_usrAgt.indexOf("win98")!=-1) || (imm_usrAgt.indexOf("windows 98")!=-1);
var imm_isWinME = (imm_usrAgt.indexOf("win95")!=-1)  && imm_isNN;
var imm_isWin2k = (imm_usrAgt.indexOf("winnt")!=-1) || (imm_usrAgt.indexOf("windows nt 5.0")!=-1);
At the time of this writing, Immersion TouchSense Technology is supported on the Microsoft Windows 98 , Microsoft Windows ME Windows 2000 operating systems. The Immersion Web Plugin will install and function correctly on the following browsers: Microsoft Internet Explorer version 4 or greater and Netscape Navigator version 4.5 to version 4.75. If a user is viewing the touch-enabled page in an unsupported browser version or on an unsupported operating system, touch sensations must be turned off to avoid error messages.

If the user is viewing the touch-enabled web page on a supported combination of operating system and browser, it is next important to detect whether the Immersion Web Plugin is installed and registered on the user's computer.

For Netscape Navigator, the detection is performed as follows:
  if(navigator.plugins["Immersion Web Netscape Plugin"]);
  { <Turn touch sensations ON> }
  else
  { ... }
For Microsoft Internet Explorer, the detection is performed as follows:
 if(document.ImmWeb.ImmWebInstalled)
  { <Turn touch sensations ON> }
  else
  { ... }
Allowing touch sensations to be turned on and off simply involves always checking the value of a global boolean (true or false value) variable before calling any methods of the Immersion Web Plugin from within a script in the web page. Touch sensations are turned on when the variable's value is 'true' and turned off when the value is 'false'. Here is an example:
  // Create global boolean variable
  var imm_onTouch = false;

  // Detect browser type and version and whether plugin is installed
  if(imm_isIE4plus && document.ImmWeb.ImmWebInstalled) {
    imm_onTouch = true;
  }
  if(imm_isNN45plus &&  !imm_isNN6plus && navigator.plugins["Immersion Web Netscape Plugin"]) {
    imm_onTouch = true;
  }

  // Function definition within <SCRIPT> tags
  function imm_initEffect( )
  {
   if(imm_onTouch) {
     // Calls to plugin methods are not made unless imm_onTouch==true
     document.ImmWeb.MakeGrid("MyGrid");
     document.ImmWeb.StartEffect("MyGrid", -1);
   }
  }

  // Calls to ImmWeb methods from within HTML
  <A href="javascript:;"
     onmouseover="if(imm_onTouch){document.ImmWeb.StartEffect('MyEffect', 0)}"
     onmouseout="if(imm_onTouch) {document.ImmWeb.StopEffect('MyEffect', 0)}">
    <IMG source="myImage.gif"></A>
If the user's system is sufficient, but the Immersion Web Plugin is not detected as an installed component, the user should be given a chance to install the plugin. Ask the user if installation is desired. If the user agrees to install the plugin, direct the browser to one of the following URLs:

http://www.immersion.com/plugins/download_IE_plugin.html for Internet Explorer

http://www.immersion.com/plugins/download_NN_plugin.html for Netscape Navigator

After installation, a link on each of these pages will return the user to the previous page, which can now be fully experienced, with touch sensations turned on.

If the user refuses the plugin installation, he or she may also not wish to be prompted to install the plugin again when viewing other touch-enabled pages. The user's wishes may be recorded in a cookie, and the cookie checked before again prompting the user to install the Immersion Web Plugin.

The relevant section of example HTML and JavaScript code appears below:
...

<OBJECT
classid="CLSID:5CA42785-ABC3-11d2-9F81-00104B2225C5"
codebase="#version=3,2,2,1"
id="ImmWeb"
height="0" width="0">
  <EMBED type="application/x-Immersion-Web-Plugin"
  name="ImmWeb" hidden="true" src="myfile.txt">
</OBJECT>

<SCRIPT language="JavaScript">
<!--hide this script from non-javascript-enabled browsers

var imm_onTouch = false;

var imm_usrAgt = navigator.userAgent.toLowerCase();
var imm_isIE = (navigator.appName == "Microsoft Internet Explorer");
var imm_isNN = (navigator.appName == "Netscape");
var imm_isIE4plus = imm_isIE && (parseInt(navigator.appVersion) >= 4);
var imm_isNN45plus = imm_isNN && (parseFloat(navigator.appVersion) >= 4.5);
var imm_isNN6plus = imm_isNN && (parseFloat(navigator.appVersion) >= 5);
var imm_isWin98 = (imm_usrAgt.indexOf("win98")!=-1) || (imm_usrAgt.indexOf("windows 98")!=-1);
var imm_isWinME = (imm_usrAgt.indexOf("win95")!=-1)  && imm_isNN;
var imm_isWin2k = (imm_usrAgt.indexOf("winnt")!=-1) || (imm_usrAgt.indexOf("windows nt 5.0")!=-1);
var imm_supportsImm = imm_isWin98 || imm_isWin2k || imm_isWinME;
var imm_NNMinPlugin = new Array(3, 2, 2, 1);
var imm_IEDontAskOff = (IMM_getCookie("DontAskIE")!= "ON");
var imm_NNDontAskOff = (IMM_getCookie("DontAskNN")!= "ON");

if(imm_supportsImm)  {
  IMM_sufficientSystem();
}

function IMM_sufficientSystem()  {
// If Netscape Navigator 4.5 or greater
if(imm_isNN45plus && !imm_isNN6plus)  {
  if(navigator.plugins["Immersion Web Netscape Plugin"] &&
     IMM_sufficientNNPlugin())  {
    imm_onTouch=true;
  }
  else  {    // ImmWeb plugin is not installed
    if(imm_NNDontAskOff)  {
      imm_installNow = confirm("You must install the Immersion Web plugin to experience tactile sensations on this web page.  Install now?");
      if(imm_installNow)  {
        self.location.href="http://www.immersion.com/plugins/download_NN_plugin.html"
      }
      else  {
        imm_askAgain = confirm("You have chosen not to install the Immersion Web plugin at this time.  Would you like to be reminded again later?");
        if(!imm_askAgain)  {
          IMM_setCookie("DontAskNN", "ON", "month");
        }
        else  {
          IMM_setCookie("DontAskNN", "ON", "now");
        }
      }
    }
  }
}

// If Internet Explorer 4 or greater
if(imm_isIE4plus)  {
  if(document.ImmWeb.ImmWebInstalled)  {
    imm_onTouch=true;
  }
  else  {    // ImmWeb plugin is not installed
    if(imm_IEDontAskOff)  {
      imm_installNow = confirm("You must install the Immersion Web plugin to experience tactile sensations on this web page.  Install now?");
      if(imm_installNow)  {
        self.location.href="http://www.immersion.com/plugins/download_IE_plugin.html"
      }
      else  {
        imm_askAgain = confirm("You have chosen not to install the Immersion Web plugin at this time.  Would you like to be reminded again later?");
        if(!imm_askAgain)  {
          IMM_setCookie("DontAskIE", "ON", "month");
        }
        else  {
          IMM_setCookie("DontAskIE", "ON", "now");
        }
      }
    }
  }
}
}   // end function IMM_sufficientSystem()

function IMM_sufficientNNPlugin()  {
    // Assumes Netscape plugin description = "Immersion Web Plugin a.b.c.d" where a.b.c.d = version
    var needDownload = false;
    var installedVersion = navigator.plugins["Immersion Web Netscape Plugin"].description.split(" ")[3].split(".");
    // Need Download if installed plugin version < minimum plugin version
    for(index=0; index<4; index++)  {
            if(installedVersion[index] > imm_NNMinPlugin[index])  {
            break;
        }
        else if(installedVersion[index] < imm_NNMinPlugin[index])  {
            needDownload = true;
            break;
        }
    }
    return (!needDownload);
}   // end function IMM_sufficientNNPlugin()

//****** Cookie utility functions ******//

function IMM_setCookie(name, value, expire) {
  var today = new Date();
  var expiry = new Date();

  switch(expire)  {
    case "day":
      expiry.setTime(today.getTime() + 1000*60*60*24*1);
      break;
    case "week":
      expiry.setTime(today.getTime() + 1000*60*60*24*7);
      break;
    case "month":
      expiry.setTime(today.getTime() + 1000*60*60*24*30);
      break;
    case "year":
      expiry.setTime(today.getTime() + 1000*60*60*24*365);
      break;
    default:
      expiry.setTime(today.getTime());
  }
  document.cookie = name + "=" + escape(value) + "; path=/; expires=" + expiry.toGMTString()
}

function IMM_getCookie(Name) {
  var search = Name + "="
  if (document.cookie.length > 0) {                   // if there are any cookies
    offset = document.cookie.indexOf(search)
    if (offset != -1) {                               // if cookie exists
      offset += search.length                         // set index of beginning of value
      end = document.cookie.indexOf(";", offset)      // set index of end of cookie value
      if (end == -1)
        end = document.cookie.length
      return unescape(document.cookie.substring(offset, end))
    }
  }
}

// stop hiding -->
</SCRIPT>

...


Immersion Web Plugin Tips and Details

Working with any new technology can be frustrating when you're still scrambling up the learning curve. Take advantage of the experience of others by reading through the tips below. It's possible that the solution to that annoying problem you've been having is already known. If you don't find what you're looking for in the entries below, please send a detailed description of the problem (including information about platforms, software versions, and what you're trying to do) to developer@immersion.com, and we can look into it together.

The Immersion Web Plugin Object Reference in an HTML Page

An HTML object reference supporting both IE and Netscape browsers looks like this:

<OBJECT
    classid="CLSID:5CA42785-ABC3-11d2-9F81-00104B2225C5"
    codebase="#version=3,2,2,1"
    id="ImmWeb"
    height="0" width="0">
  <EMBED type="application/x-Immersion-Web-Plugin"
      name="ImmWeb" hidden="true" src="myfile.txt">
</OBJECT>
The OBJECT tag is relevant when the page is being viewed in Microsoft Internet Explorer. The codebase attribute of the OBJECT tag, as seen above, specifies the minimum version of the Immersion Web Plugin necessary to support this HTML page. No download path is included in this attribute so that plugin download will only be triggered in response to plugin detection.

A Netscape browser does not process the OBJECT tag, and instead looks directly at the contained EMBED tag. The MIME type indicated in the type attribute is specific to the Netscape version of the Immersion Web Plugin, and is only recognized when this plugin is installed on the client machine.

The src attribute must be present in the EMBED tag. Without this attribute, an Internet Explorer browser viewing the touch-enabled page on a client machine without the Immersion Web Plugin installed may either give error messages or incorrectly render the page (smear the page contents). The indicated file in the src attribute, "myfile.txt", does not actually need to exist, but the specified filename does need to have a universally-recognizable extension, such as ".txt" or ".html", to prevent misbehavior in Internet Explorer. See below.

Placement of TouchSense-Enabling Code in an HTML Page

In a Netscape browser, the plugin referred to in the EMBED tag, even when specified as "hidden", takes up some screen real estate. Therefore, to prevent any disruption to graphics at the top of a web page, the object references (OBJECT and EMBED tags) should be placed below the page content.

Plugin detection code, in SCRIPT tags, must be placed below the object references in the web page in order to function properly.

It is important to check that all function definitions in all touch-enabling scripts have fully loaded into the page before these functions are called. Mouse movement events such as onmouseover and onmouseout can fire even before a page completely loads, causing errors when the functions they call are not found. Be sure to surround each function call triggered by an event with a check for the value of a boolean variable indicating page and script loading status. This variable is initially set to FALSE, in a script at the top of the page, and is set to TRUE only when all scripts have successfully loaded. For further details, see below. This approach can also provide a seamless solution if external script files (.js files) are used, and the browser being used to view the page is too old to support the loading of external scripts.

Prevention of Strange Behaviors in Touch-Enabled Pages

Behavior:

Page contents smear into an unintelligible mess when the page is scrolled.

Description and Solution:

This happens in the following situation:

  • Internet Explorer is the browser
  • Client machine DOES NOT HAVE the Immersion Web Plugin installed
  • Page has been refreshed one or more times, or multiple touch-enabled pages with the same code error have been visited in a single browser session.

Once this problem occurs, other touch-enabled pages will not be rendered properly until the browser has been closed and re-launched.

This problem is solved by making sure the src attribute is present in the EMBED tag of the Immersion Web Plugin object references. This attribute must indicate a filename with a common extension, such as ".txt" or ".html". The file itself does not have to exist, and is not actually loaded or used by the plugin.

Behavior:

Error messages appear, referring to nonexistent syntax errors in a correctly-written script whenever a JavaScript-triggering event occurs (such as a mouseover on a navigation element of the page).

Description and Solution:

Similar types of behavior can occur for a number of reasons, but if you've checked your JavaScript code carefully, and it is written correctly, the following situation may exist:

  • Internet Explorer is the browser
  • Client machine HAS the Immersion Web Plugin installed
  • META tag specifying a character set for the page is missing, and the browser is incorrectly assigning a default character set, such as "utf-7", to the page.

This problem is solved by including the following tag in the HTML code in the HEAD section of the page:

<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

The character set chosen and specified in the charset attribute should be appropriate for the text content of the page. However, make sure this character set is properly understood on all browser/platform combinations, or other errors or bad behaviors can result.

Behavior:

When a page is first loaded, runtime error messages occasionally appear, with "Error: Object Expected."

Description and Solution:

This occurs when a JavaScript function is called from a UI element (for example, a call triggered by an onmouseover event over an image) before the function definition has been loaded into the page. The function, when called, does not appear to exist, and an error is generated.

This problem is solved by checking that all scripts in the page have loaded before calling any functions defined in these scripts. A boolean variable, something like "imm_pageLoaded", is declared and set to FALSE in a script at the top of the page. The very last script statement in the very last script block to load into the page sets the value of this boolean variable to TRUE. A JavaScript function is only called from any point in the page after checking that the value of imm_pageLoaded is TRUE.

Here's an example:

<!-- script at top of web page -->
<SCRIPT>
  var imm_pageLoaded = FALSE;
</SCRIPT>

<!-- IMG in middle of web page; mouse events trigger function calls -->
<A href="javascript:;"
   onmouseover="if(imm_pageLoaded) {SomeJavaScriptFunction('MyEffect');}"
   onmouseout="if(imm_pageLoaded) {SomeOtherFunction();}">
  <IMG source="myImage.gif"></A>

<!-- script at bottom of web page -->
<SCRIPT>
  [... function definitions, other code ...]

  imm_pageLoaded = TRUE;
</SCRIPT>

Immersion Web Plugin Details

Immersion Web Plugin for Microsoft Internet Explorer

Files:

  • IMMWEB.OCX
  • IFCXX.DLL (where XX is 20, 21, ... depending on the version of immweb.ocx being used)
  • ICOMMON.DLL, if using a Plugin version less than 3.2.1.0
  • MFC42.DLL and MSVCRT.DLL (Microsoft libraries), if using a Plugin version less than 3.2.1.0

Installation:

Plugin is automatically installed when the currently installed plugin is of a lesser version than specified, or when no plugin is installed on the client machine. Plugin components are contained in a CAB archive called ImmWeb.cab. A page will trigger automatic installation when the codebase attribute in the OBJECT tag specifies both the desired plugin version and the URL of the necessary CAB file:

<OBJECT
    classid="CLSID:5CA42785-ABC3-11d2-9F81-00104B2225C5"
    codebase="http://www.immersion.com/plugins/ImmWeb.cab#version=3,2,2,1"
    id="ImmWeb"
    height="0" width="0">
  <EMBED type="application/x-Immersion-Web-Plugin"
      name="ImmWeb" hidden="true" src="myfile.txt">
</OBJECT>

Uninstallation:

IFCXX.DLL and ICOMMON.DLL are installed into the WINDOWS\system folder. IMMWEB.OCX is normally installed into the WINDOWS\Downloaded Program Files directory. To uninstall, right-click the entry titled "Immersion Web ActiveX Control" and select "Remove." To manually uninstall the plugin if the .OCX file is located elsewhere:

  • locate IMMWEB.OCX on your machine
  • unregister the file at the MS-DOS Prompt (WINDOWS\system\regsvr32.exe /u IMMWEB.OCX)
  • delete the file IMMWEB.OCX

Immersion Web Plugin for Netscape Navigator or Communicator

Files (in addition to the files listed above for Internet Explorer):

  • NPIMMWEB.CLASS
  • NPIMMWEB.DLL

Installation:

The necessary files for the Netscape version of the Immersion Web Plugin are installed automatically either from a page with a SmartUpdate installation script, or when the JAR file containing the Plugin is opened in a Netscape browser. If the SmartUpdate installation does not work, the Plugin can be installed manually:

  • install the Immersion Web Plugin for Internet Explorer, as above
  • extract the files NPIMMWEB.CLASS and NPIMMWEB.DLL from the JAR archive using an application like WinZip
  • place these two files into the Netscape Plugins folder, located at Netscape\Communicator\Program\Plugins.

Uninstallation:

In addition to the files IMMWEB.OCX, IFCXX.DLL, and ICOMMON.DLL, which are installed into WINDOWS\system, the above files, specific to Netscape, are installed into Netscape's Plugins folder, at Netscape\Communicator\Program\Plugins. The Immersion Web Plugin for Netscape can be uninstalled manually by deleting the files NPIMMWEB.CLASS and NPIMMWEB.DLL from the Netscape Plugins folder.


Notes for C/C++ Developers

The Immersion Web Plugin is actually an ActiveX control. Thus, developers can embed it in their C and C++ applications. This page gives some critical information on using the Immersion Web Plugin in this manner. It assumes the reader understands COM and is purely for reference.

A Note About Enumerations:

Several methods of IImmWeb and IImmWeb2 receive or return an enumerated type. However, the Immersion Web Plugin reference describes these methods as receiving or returning integers. This is because the reference is geared towards Web developers who use loosely typed languages. Consult the specific enumerations below to see what methods are affected (demarked by Related Methods).

Immersion Web Type Library (ImmWebLib)
GUID: | 174ADFA0-AF90-11d2-9F81-00104B2225C5
Version: | 3.22
Contains: | ImmWebControl, IImmWeb, IImmWeb2
Immersion Web ActiveX Control (ImmWebControl)
Control Version: | 3.2.2.1
GUID: | 5CA42785-ABC3-11D2-9F81-00104B2225C5
ProgID: | Immersion.ImmWebControl.2
Supported Interfaces: | IImmWeb, IImmWeb2
Immersion Web Interface (IImmWeb)
GUID:
 5CA42783-ABC3-11d2-9F81-00104B2225C5
Supported Interfaces:
 IDispatch
Properties:
 DeviceFlag (EImmWebDeviceFlag), LastError (long)
Enumerations:
 EImmWebAxis, EImmWebDeviceFlag, EImmWebWaveform
Methods:
ChangeCenter | ChangeRectangle | GetNumberOfEffects | MakePeriodic2
ChangeClippingMask | ChangeSaturation | GetScreenPosX | MakeRamp
ChangeCoefficient | ChangeSpacing | GetScreenPosY | MakeSpring
ChangeDeadBand | ChangeStartDelay | MakeConstant | MakeSpring2
ChangeDirection | ChangeStiffness | MakeDamper | MakeTexture
ChangeDirectionPolar | ChangeStiffnessMask | MakeDamper2 | OpenForceResource
ChangeDuration | ChangeStrength | MakeEllipse | StartEffect
ChangeEnvelope | ChangeThickness | MakeEnclosure | StartEffect2
ChangeGain | ChangeViscosity | MakeFriction | StopEffect
ChangeMagnitude | GetDeviceFlag | MakeFriction2 | StopEffects
ChangeMinimum | GetDevicePosX | MakeGrid | TouchSenseDeviceAttached
ChangeOffset | GetDevicePosY | MakeInertia |
ChangePeriod | GetLastError | MakeInertia2 |
ChangePhase | GetNameOfEffect | MakePeriodic |
Immersion Web Interface 2 (IImmWeb2)
GUID:
 47945DF4-CF77-4061-A01F-A7D8C5F6AF4E
Supported Interfaces:
 IDispatch, IImmWeb
Enumerations:
 EImmWebDeviceType, EImmWebTechnologyType
Methods:
ChangeCoefficientX | GetCoefficientPositiveX | GetIDesktopVersion | GetSaturation2
ChangeCoefficientY | GetCoefficientPositiveY | GetIFCVersion | GetSaturationNegativeX
ChangeDeadBandX | GetCursorPosX | GetImmAPIVersion | GetSaturationNegativeY
ChangeDeadBandY | GetCursorPosY | GetMagnitude | GetSaturationPositiveX
ChangeMagnitudeX | GetDeadBandX | GetMagnitude2 | GetSaturationPositiveY
ChangeMagnitudeY | GetDeadBandY | GetMagnitudeNegativeX | GetSpacingNegativeX
ChangeMinimumX | GetDeviceProductName | GetMagnitudeNegativeY | GetSpacingNegativeY
ChangeMinimumY | GetDeviceType | GetMagnitudePositiveX | GetSpacingPositiveX
ChangeSaturationX | GetDeviceTypeName | GetMagnitudePositiveY | GetSpacingPositiveY
ChangeSaturationY | GetDeviceTechnology | GetMinimumX | GetSpacingX
ChangeSpacingX | GetDeviceTechnologyName | GetMinimumY | GetSpacingY
ChangeSpacingY | GetDirectionX | GetNameOfEffectInCompound | GetStartDelay
ChangeThicknessX | GetDirectionY | GetNumberOfEffectsInCompound | GetStiffness
ChangeThicknessY | GetDirectionPolar | GetOffset | GetStiffness2
EffectExists | GetDriverVersion | GetOffset2 | GetStiffnessMask
EffectSupportsChange | GetDuration | GetPeriod | GetThickness
EffectSupportsGet | GetDXVersion | GetPhase | GetThickness2
GetAxis | GetEffectTypeName | GetPluginVersion | GetThicknessNegativeX
GetCenterX | GetEnvelopeAttackLevel | GetRectangleLeft | GetThicknessNegativeY
GetCenterY | GetEnvelopeAttackTime | GetRectangleTop | GetThicknessPositiveX
GetClippingMask | GetEnvelopeFadeLevel | GetRectangleWidth | GetThicknessPositiveY
GetCoefficientNegativeX | GetEnvelopeFadeTime | GetRectangleHeight | GetWaveform
GetCoefficientNegativeY | GetGain | GetSaturation |
Axis Enumeration (EImmWebAxis)
Member of Interface:
 IImmWeb
Related Methods:
 GetAxis, MakeDamper2, MakeFriction2, MakeGrid2,
MakeInertia2, MakeSpring2, MakeTexture
Name | Value | Description
axDirectional | 0x00 | Directional
axXAxis | 0x01 | X Axis
axYAxis | 0x02 | Y Axis
axBothAxes | 0x03 | X and Y Axes
Device Flag Enumeration (EImmWebDeviceFlag)
Member of Interface:
 IImmWeb
Related Methods:
 GetDeviceFlag
Name | Value | Description
dfForbidDirectXDevice | 0x00 | Forbid DirectX Device
dfAllowDirectXDevice | 0x01 | Allow DirectX Device
dfPreferDirectXDevice | 0x02 | Prefer DirectX Device
dfRequireDirectXDevice | 0x03 | Require DirectX Device
Waveform Enumeration (EImmWebWaveform)
Member of Interface:
 IImmWeb
Related Methods:
 GetWaveform, MakePeriodic2
Name | Value | Description
wfSine | 0x00 | Sine Wave
wfSquare | 0x01 | Square Wave
wfTriangle | 0x02 | Triangle Wave
wfSawToothUp | 0x03 | Saw Tooth Up Wave
wfSawToothDown | 0x04 | Saw Tooth Down Wave
Device Type Enumeration (EImmWebDeviceType)
Member of Interface:
 IImmWeb2
Related Methods:
 GetDeviceType
Name | Value | Description
dtOther | 0x00 | Other Device
dtJoystick | 0x01 | Joystick
dtWheel | 0x02 | Wheel
dtGamepad | 0x03 | Gamepad
dtAbsoluteMouse | 0x04 | Absolute Mouse
dtRelativeMouse | 0x05 | Relative Mouse
Technology Type Enumeration (EImmWebTechnologyType)
Member of Interface:
 IImmWeb2
Related Methods:
 GetDeviceTechnology
Name | Value | Description
ttOther | 0x00 | Other Technology
ttVibro | 0x01 | Vibrotactile
ttIHD | 0x02 | Inertial Harmonic Drive
ttFullFF | 0x03 | Full Force-Feedback


Supported Effects

Immersion Web Plugin Reference

Effects Supported by the Immersion Web Plugin

The following effects are accessible using the Immersion Web Plugin. The nature of these effects are described in detail in the Immersion TouchSense Fundamentals document. Each effect supports a different set of Change Property methods. The effects can be created using either a Make Effect method or by opening an IFR file using OpenForceResource. Finally, the effects can be started and stopped using StartEffect, StartEffect2, StopEffect and StopEffects.

Compound effects can be loaded using OpenForceResource and played using StartEffect, StartEffect2, Stop Effect and StopEffects. However, dynamically making and changing compound effects is not yet supported.

Supported Effects
Compound
Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture


Compound Effect

Immersion Web Plugin Reference

Compound

A compound effect is an effect which stores multiple effect primitives. When you start and stop a compound effect, you simultaneously start and stop all the primitives in that effect. A compound effect can only be created by loading one from an IFR using OpenForceResource. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
None. |


Constant Effect

Immersion Web Plugin Reference

Constant

A constant effect is created using the MakeConstant method or by using OpenForceResource to open an .IFR (Immersion Force Resource) file containing a constant effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeMagnitude ChangeMinimum ChangeStartDelay | GetEffectTypeName GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMagnitude GetMagnitude2 GetStartDelay


Damper Effect

Immersion Web Plugin Reference

Damper

A damper effect is created using the MakeDamper or MakeDamper2 methods or by using OpenForceResource to open an .IFR file containing a damper effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeCenter ChangeCoefficient ChangeCoefficientX ChangeCoefficientY ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeMinimum ChangeMinimumX ChangeMinimumY ChangeSaturation ChangeSaturationX ChangeSaturationY ChangeStartDelay ChangeViscosity | GetEffectTypeName GetAxis GetCenterX GetCenterY GetCoefficientPositiveX GetCoefficientPositiveY GetCoefficientNegativeX GetCoefficientNegativeY GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMinimumX GetMinimumY GetSaturation GetSaturation2 GetSaturationPositiveX GetSaturationPositiveY GetSaturationNegativeX GetSaturationNegativeY GetStartDelay


Ellipse Effect

Immersion Web Plugin Reference

Ellipse

An ellipse effect is created using the MakeEllipse method or by using OpenForceResource to open an .IFR file containing an ellipse effect. The following table lists its supported Change property and Get property methods.

Supported Change Propery Methods | Supported Get Property Methods
ChangeCenter ChangeClippingMask ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeInsideEffect ChangeRectangle ChangeSaturation ChangeStartDelay ChangeStiffness ChangeStiffnessMask ChangeThickness | GetEffectTypeName GetCenterX GetCenterY GetClippingMask GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetRectangleLeft GetRectangleTop GetRectangleWidth GetRectangleHeight GetSaturation GetSaturation2 GetStartDelay GetStiffness GetStiffness2 GetStiffnessMask GetThickness GetThickness2


Enclosure Effect

Immersion Web Plugin Reference

Enclosure

An enclosure effect is created using the MakeEnclosure method or by using OpenForceResource to open an .IFR file containing an enclosure effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeCenter ChangeClippingMask ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeInsideEffect ChangeRectangle ChangeSaturation ChangeStartDelay ChangeStiffness ChangeStiffnessMask ChangeThickness | GetEffectTypeName GetCenterX GetCenterY GetClippingMask GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetRectangleLeft GetRectangleTop GetRectangleWidth GetRectangleHeight GetSaturation GetSaturation2 GetStartDelay GetStiffness GetStiffness2 GetStiffnessMask GetThickness GetThickness2


Friction Effect

Immersion Web Plugin Reference

Friction

A friction effect is created using the MakeFriction or MakeFriction2 methods or by using OpenForceResource to open an .IFR file containing a friction effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeCenter ChangeCoefficient ChangeCoefficientX ChangeCoefficientY ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeMinimum ChangeMinimumX ChangeMinimumY ChangeSaturation ChangeSaturationX ChangeSaturationY ChangeStartDelay | GetEffectTypeName GetAxis GetCenterX GetCenterY GetCoefficientPositiveX GetCoefficientPositiveY GetCoefficientNegativeX GetCoefficientNegativeY GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMinimumX GetMinimumY GetSaturation GetSaturation2 GetSaturationPositiveX GetSaturationPositiveY GetSaturationNegativeX GetSaturationNegativeY GetStartDelay


Grid Effect

Immersion Web Plugin Reference

Grid

A grid effect is created using the MakeGrid or MakeGrid2 methods or by using OpenForceResource to open an .IFR file containing a grid effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeCenter ChangeCoefficient ChangeCoefficientX ChangeCoefficientY ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeOffset ChangeSaturation ChangeSaturationX ChangeSaturationY ChangeSpacing ChangeStartDelay ChangeStrength | GetEffectTypeName GetAxis GetCenterX GetCenterY GetCoefficientPositiveX GetCoefficientPositiveY GetCoefficientNegativeX GetCoefficientNegativeY GetDeadBandX GetDeadBandY GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetOffset GetOffset2 GetSaturation GetSaturation2 GetSaturationPositiveX GetSaturationPositiveY GetSaturationNegativeX GetSaturationNegativeY GetSpacingX GetSpacingY GetStartDelay


Inertia Effect

Immersion Web Plugin Reference

Inertia

An inertia effect is created using the MakeInertia or MakeInertia2 methods or by using OpenForceResource to open an .IFR file containing an inertia effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeCenter ChangeCoefficient ChangeCoefficientX ChangeCoefficientY ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeMinimum ChangeMinimumX ChangeMinimumY ChangeOffset ChangeSaturation ChangeSaturationX ChangeSaturationY ChangeStartDelay | GetEffectTypeName GetAxis GetCenterX GetCenterY GetCoefficientPositiveX GetCoefficientPositiveY GetCoefficientNegativeX GetCoefficientNegativeY GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMinimumX GetMinimumY GetSaturation GetSaturation2 GetSaturationPositiveX GetSaturationPositiveY GetSaturationNegativeX GetSaturationNegativeY GetStartDelay


Periodic Effect

Immersion Web Plugin Reference

Periodic

A periodic effect is created using the MakePeriodic or MakePeriodic2 methods or by using OpenForceResource to open an .IFR file containing a periodic effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeMagnitude ChangeOffset ChangePeriod ChangePhase ChangeStartDelay | GetEffectTypeName GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMagnitude GetMagnitude2 GetOffset GetOffset2 GetPeriod GetPhase GetStartDelay GetWaveform


Ramp Effect

Immersion Web Plugin Reference

Ramp

A ramp effect is created using the MakeRamp method or by using OpenForceResource to open an .IFR file containing a ramp effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeMagnitude ChangeStartDelay | GetEffectTypeName GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMagnitude GetMagnitude2 GetStartDelay


Spring Effect

Immersion Web Plugin Reference

Spring

A spring effect is created using the MakeSpring or MakeSpring2 methods or by using OpenForceResource to open an .IFR file containing a spring effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeCenter ChangeCoefficient ChangeCoefficientX ChangeCoefficientY ChangeDeadBand ChangeDeadBandX ChangeDeadBandY ChangeDirection ChangeDirectionPolar ChangeDuration ChangeEnvelope ChangeGain ChangeSaturation ChangeSaturationX ChangeSaturationY ChangeStartDelay ChangeStiffness | GetEffectTypeName GetAxis GetCenterX GetCenterY GetCoefficientPositiveX GetCoefficientPositiveY GetCoefficientNegativeX GetCoefficientNegativeY GetDeadBandX GetDeadBandY GetDirectionX GetDirectionY GetDirectionPolar GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetSaturation GetSaturation2 GetSaturationPositiveX GetSaturationPositiveY GetSaturationNegativeX GetSaturationNegativeY GetStartDelay GetStiffness GetStiffness2


Texture Effect

Immersion Web Plugin Reference

Texture

A texture effect is created using the MakeTexture method or by using OpenForceResource to open an .IFR file containing a texture effect. The following table lists its supported Change property and Get property methods.

Supported Change Property Methods | Supported Get Property Methods
ChangeDuration ChangeEnvelope ChangeGain ChangeMagnitude ChangeMagnitudeX ChangeMagnitudeY ChangeOffset ChangeSpacing ChangeSpacingX ChangeSpacingY ChangeStartDelay ChangeThickness ChangeThicknessX ChangeThicknessY | GetEffectTypeName GetDuration GetEnvelopeAttackLevel GetEnvelopeAttackTime GetEnvelopeFadeLevel GetEnvelopeFadeTime GetGain GetMagnitude GetMagnitude2 GetMagnitudePositiveX GetMagnitudePositiveY GetMagnitudeNegativeX GetMagnitudeNegativeY GetOffset GetOffset2 GetSpacingX GetSpacingY GetSpacingPositiveX GetSpacingPositiveY GetSpacingNegativeX GetSpacingNegativeY GetStartDelay GetThickness GetThickness2 GetThicknessPositiveX GetThicknessPositiveY GetThicknessNegativeX GetThicknessNegativeY


Methods of the Immersion Web Plugin

The following methods are accessible using the Immersion Web Plugin:

  • Change Property Methods
  • Device Management Methods
  • Effect Play and Management Methods
  • Get Property Methods
  • Make Effect Methods
  • Version Information Methods

Change Property Methods
ChangeCenter | ChangeDuration | ChangeOffset | ChangeStartDelay
ChangeClippingMask | ChangeEnvelope | ChangePeriod | ChangeStiffness
ChangeCoefficient | ChangeGain | ChangePhase | ChangeStiffnessMask
ChangeCoefficientX | ChangeInsideEffect | ChangeRectangle | ChangeStrength
ChangeCoefficientY | ChangeMagnitude | ChangeSaturation | ChangeThickness
ChangeDeadBand | ChangeMagnitudeX | ChangeSaturationX | ChangeThicknessX
ChangeDeadBandX | ChangeMagnitudeY | ChangeSaturationY | ChangeThicknessY
ChangeDeadBandY | ChangeMinimum | ChangeSpacing | ChangeViscosity
ChangeDirection | ChangeMinimumX | ChangeSpacingX |
ChangeDirectionPolar | ChangeMinimumY | ChangeSpacingY |

Device Management Methods
GetCursorPosX
GetCursorPosY
GetDeviceFlag
GetDevicePosX
GetDevicePosY
GetDeviceProductName
GetDeviceType
GetDeviceTypeName
GetDeviceTechnology
GetDeviceTechnologyName
GetScreenPosX
GetScreenPosY
TouchSenseDeviceAttached

Effect Play and Management Methods
EffectExists
EffectSupportsChange
EffectSupportsGet
GetLastError
GetNameOfEffect
GetNumberOfEffects
OpenForceResource
StartEffect
StartEffect2
StopEffect
StopEffects

Get Property Methods
GetEffectTypeName | GetEnvelopeAttackLevel | GetPeriod | GetSpacingPositiveY
GetAxis | GetEnvelopeAttackTime | GetPhase | GetSpacingX
GetCenterX | GetEnvelopeFadeLevel | GetRectangleLeft | GetSpacingY
GetCenterY | GetEnvelopeFadeTime | GetRectangleTop | GetStartDelay
GetClippingMask | GetGain | GetRectangleWidth | GetStiffness
GetCoefficientNegativeX | GetMagnitude | GetRectangleHeight | GetStiffness2
GetCoefficientNegativeY | GetMagnitude2 | GetSaturation | GetStiffnessMask
GetCoefficientPositiveX | GetMagnitudeNegativeX | GetSaturation2 | GetThickness
GetCoefficientPositiveY | GetMagnitudeNegativeY | GetSaturationNegativeX | GetThickness2
GetDeadBandX | GetMagnitudePositiveX | GetSaturationNegativeY | GetThicknessNegativeX
GetDeadBandY | GetMagnitudePositiveY | GetSaturationPositiveX | GetThicknessNegativeY
GetDirectionX | GetMinimumX | GetSaturationPositiveY | GetThicknessPositiveX
GetDirectionY | GetMinimumY | GetSpacingNegativeX | GetThicknessPositiveY
GetDirectionPolar | GetOffset | GetSpacingNegativeY | GetWaveform
GetDuration | GetOffset2 | GetSpacingPositiveX |

Make Effect Methods
MakeConstant | MakeInertia
MakeDamper | MakeInertia2
MakeDamper2 | MakePeriodic
MakeEllipse | MakePeriodic2
MakeEnclosure | MakeRamp
MakeFriction | MakeSpring
MakeFriction2 | MakeSpring2
MakeGrid | MakeTexture
MakeGrid2 | OpenForceResource

Version Information Methods
GetDriverVersion
GetDXVersion
GetIDesktopVersion
GetIFCVersion
GetImmAPIVersion
GetPluginVersion
ImmWebInstalled


Change Effect Property Methods

Once an effect is created, its parameters can be changed using any of the many Change methods listed below. Change methods have the general form:

BOOL Change<Property>(<effect-name>, <resource-reference>, <arguments>)

For example, to change the "Direction" property of an effect you might call:

ChangeDirection("My Effect", 0, 100, 150);

If "My Effect" is a compound effect, the property will be changed on all sub-effects that support the property. If called on a compound effect containing multiple sub-effects, the Change method is considered successful only if the property is successfully changed on EVERY sub-effect.

Pass in the name of the effect, the resource-reference returned by OpenForceResource, and the new property values. Pass -1 for the resource reference to use an effect created with a Make method.

The Change methods will return TRUE if successful, FALSE otherwise. Not all effects support all properties. If you attempt to change the property of an effect that does not support the property, FALSE will be returned. The table below shows which effects support which methods. If the cell for the effect-property combination is blank, then it is not supported.

This table defines the available properties and how many arguments are necessary to set them on the various effects. This is intended as a summary, not an exhaustive reference for using the methods to change these properties. For a detailed look at how to change each supported property for each of the available effects, please examine the documentation for the individual effects or the individual Change Property methods. You can query whether an effect supports changing a particular property by calling EffectSupportsChange.

Effect-Property Combinations

Properties

Constant Damper Ellipse Enclosure Friction Grid Inertia Periodic Ramp Spring Texture
Center | 2 | 2 | 2 | 2 | 2 | 2 | 2
ClippingMask | 1 | 1
Coefficient | 2 | 2 | 2 | 2 | 2
CoefficientXY | 2 | 2 | 2 | 2 | 2
Deadband | 1 | 1
DeadbandXY | 1 | 1
Direction | 2 | 2 | 2 | 2 | 2 | 2 | 2 | 2 | 2 | 2
DirectionPolar | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1
Duration | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1
Envelope | 4 | 4 | 4 | 4 | 4 | 4 | 4 | 4 | 4 | 4 | 4
Gain | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1
InsideEffect | 2 | 2
Magnitude | 1 of 2 | 1 of 2 | 2 | 2
MagnitudeXY | 2
Minimum | 1 | 1 | 1
MinimumXY | 1 | 1 | 1
Offset | 2 | 1 of 2 | 2
Period | 1
Phase | 1
Rectangle | 4 | 4
Saturation | 2 | 1 of 2 | 2 | 2 | 2 | 2 | 2
SaturationXY | 2 | 2 | 2 | 2 | 2
Spacing | 2 | 2
SpacingXY | 2
StartDelay | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1
Stiffness | 1 of 2 | 2 | 1 of 2
StiffnessMask | 1 | 1
Strength | 2
Thickness | 1 of 2 | 2 | 2
ThicknessXY | 2
Viscosity | 1

Properties

Constant Damper Ellipse Enclosure Friction Grid Inertia Periodic Ramp Spring Texture

Each Change method takes <effect name>, <resource-reference> as its first two arguments. The numbers in the cells of the table above represent the number of additional arguments the Change method takes, according to the following table:

Additional Arguments of Change Methods
blank
 effect-property combination not supported

1

takes 1 argument

1 of 2

takes 2 arguments, but the second argument is ignored (pass 0 for ignored arguments)

2

takes 2 arguments

The following list shows the Change methods supported by the Immersion Web ActiveX Control:

Change Property Methods
ChangeCenter | ChangeDuration | ChangeOffset | ChangeStartDelay
ChangeClippingMask | ChangeEnvelope | ChangePeriod | ChangeStiffness
ChangeCoefficient | ChangeGain | ChangePhase | ChangeStiffnessMask
ChangeCoefficientX | ChangeInsideEffect | ChangeRectangle | ChangeStrength
ChangeCoefficientY | ChangeMagnitude | ChangeSaturation | ChangeThickness
ChangeDeadBand | ChangeMagnitudeX | ChangeSaturationX | ChangeThicknessX
ChangeDeadBandX | ChangeMagnitudeY | ChangeSaturationY | ChangeThicknessY
ChangeDeadBandY | ChangeMinimum | ChangeSpacing | ChangeViscosity
ChangeDirection | ChangeMinimumX | ChangeSpacingX |
ChangeDirectionPolar | ChangeMinimumY | ChangeSpacingY |


ChangeCenter

Changes the center of an effect. The meaning of "center" is dependent on the type of the effect being changed (see Supported Effects below).

boolean ChangeCenter(
    BSTR effectName,
    long lResourceReference,
    long lCenterX,
    long lCenterY
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lCenterX
The new center's X-value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lCenterY
The new center's Y-value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameters are in the range (-10000, +10000).
The parameters determine the offsets to the minimum velocity at which opposing force is applied in x and y directions. Note: If (x, y) are not set to (0, 0), forces will be applied when the mouse is stationary. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called. If a uniform damping effect is desired, this default value must be changed with ChangeCenter before the effect is started.
Ellipse
Parameters are in pixels.
The parameters determine the location of ellipse center from the top-left corner of the screen. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called. Also see ChangeRectangle.
Enclosure
Parameters are in pixels.
The parameters determine the location of enclosure center from the top-left corner of the screen. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called. Also see ChangeRectangle.
Friction
Parameters are in the range (-10000, +10000).
The parameters determine the offsets to the minimum velocity at which opposing force is applied in x and y directions. Note: If (x, y) are not set to (0, 0), forces will be applied when the mouse is stationary. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called. If a uniform friction effect is desired, this default value must be changed with ChangeCenter before the effect is started.
Grid
Parameters are in pixels.
The parameters determine the distances from left and top edges of screen or enclosure at which first grid effect (node) is felt. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called. For a grid, this method is the same as ChangeOffset.
Inertia
Parameters are in the range (-10000, +10000).
The parameters determine the offsets to the minimum acceleration at which opposing force is applied in x and y directions. Note: If (x, y) are not set to (0, 0), forces will be applied when the mouse is not accelerating. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called. If a uniform inertia effect is desired, this default value must be changed with ChangeCenter before the effect is started.
Spring
Parameters are in pixels.
The parameters determine the distance of the spring center from the top left corner of the screen. The default value of Center set upon effect initialization is the mouse position on the screen when StartEffect is called.

Remarks

To acheive the IFC value of IMM_EFFECT_MOUSE_POS_AT_START, pass 0x7FFFFFFF for both lCenterX and lCenterY. Supplying these values will cause the assignment of the center point to be delayed until you call the StartEffect or StartEffect2 methods. At that time, the center point will be set to the current position of the mouse cursor.

When changing the center of a single-axis effect, only one of the lCenterX or lCenterY arguments is considered — the one that corresponds to the axis of the condition. The other argument is ignored.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeOffset, ChangeRectangle, GetCenterX, GetCenterY.


ChangeClippingMask

Changes the clipping mask of an effect. A clipping mask specifies which walls of a shape have cursor clipping (a visual effect giving the illusion of wall impenetrability) active. This method applies only to enclosures and ellipses (see Supported Effects below).

boolean ChangeClippingMask(
    BSTR effectName,
    long lResourceReference,
    long lClippingMask
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lClippingMask
The mask to specify which walls of the effect have cursor clipping active. See Supported Effects below to see what values to pass for a particular effect.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Ellipse
The parameter is a mask created by OR-ing the flags below.
Ellipse Clipping Masks
Flag

Any inner wall

0x66

Any outer wall

0x99

Any wall

0xFF

Enclosure
The parameter is a mask created by OR-ing the flags below.
Enclosure Clipping Masks
Flag

None

0x00

Outer left wall

0x01

Inner left wall

0x02

Inner right wall

0x04

Outer right wall

0x08

Outer top wall

0x10

Inner top wall

0x20

Inner bottom wall

0x40

Outer bottom wall

0x80

Inner any wall

0x66

Outer any wall

0x99

Any wall

0xFF

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeStiffnessMask, GetClippingMask.


ChangeCoefficient

Changes the coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean ChangeCoefficient(
    BSTR effectName,
    long lResourceReference,
    long lCoefficient,
    long lCoefficient2
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lCoefficient
The first new coefficient. The meaning of this value is dependent on the type of effect being changed (see Supported Effects below).
lCoefficient2
The second new coefficient. The meaning of this value is dependent on the type of effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameters are in the range (-10000, +10000).
The parameters determine the damping coefficients, the multipliers of (velocity - minimum velocity) in positive and negative directions of mouse movement, respectively. Also see ChangeViscosity.
Friction
Parameters are in the range (-10000, +10000).
The parameters determine the friction coefficients, multipliers of (velocity - minimum velocity) in positive and negative directions of mouse movement, respectively.
Grid
Parameters are in the range (-10000, +10000).
The parameters determine the strengths of the node points in the horizontal and vertical directions, respectively, when moving over the grid. Also see ChangeStrength.
Inertia
Parameters are in the range (-10000, +10000).
The parameters determine the inertia coefficients, multipliers of (acceleration - minimum acceleration) in positive and negative directions of mouse movement, respectively.
Spring
Parameters are in the range (-10000, +10000).
The parameters determine the spring constants, the multipliers of mouse (displacement - deadband displacement) from spring center in positive and negative directions, respectively, along the spring axis/axes. Also see ChangeStiffness.

Remarks

This method assigns the same positive and negative values to both the X- and Y- axes. To independently set these axes, use ChangeCoefficientX and ChangeCoefficientY.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeCoefficientX, ChangeCoefficientY, ChangeStiffness, ChangeStrength, ChangeViscosity, GetCoefficientNegativeX, GetCoefficientNegativeY, GetCoefficientPositiveX, GetCoefficientPositiveY.


ChangeCoefficientX

Changes the X coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean ChangeCoefficientX(
    BSTR effectName,
    long lResourceReference,
    long lPositiveCoefficient,
    long lNegativeCoefficient
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveCoefficient
The new positive-X coefficient value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeCoefficient
The new negative-X coefficient value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameters are in the range (-10000, +10000).
The parameters determine the damping coefficients, the multipliers of (velocity - minimum velocity) in positive and negative directions of mouse movement, respectively. Also see ChangeViscosity.
Friction
Parameters are in the range (-10000, +10000).
The parameters determine the friction coefficients, multipliers of (velocity - minimum velocity) in positive and negative directions of mouse movement, respectively.
Grid
Parameters are in the range (-10000, +10000).
The parameters determine the strengths of the node points in the horizontal and vertical directions, respectively, when moving over the grid. Also see ChangeStrength.
Inertia
Parameters are in the range (-10000, +10000).
The parameters determine the inertia coefficients, multipliers of (acceleration - minimum acceleration) in positive and negative directions of mouse movement, respectively.
Spring
Parameters are in the range (-10000, +10000).
The parameters determine the spring constants, the multipliers of mouse (displacement - deadband displacement) from spring center in positive and negative directions, respectively, along the spring axis/axes. Also see ChangeStiffness.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeCoefficientY, GetCoefficientNegativeX, GetCoefficientPositiveX.


ChangeCoefficientY

Changes the Y coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean ChangeCoefficientY(
    BSTR effectName,
    long lResourceReference,
    long lPositiveCoefficient,
    long lNegativeCoefficient
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveCoefficient
The new positive-Y coefficient value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeCoefficient
The new negative-Y coefficient value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameters are in the range (-10000, +10000).
The parameters determine the damping coefficients, the multipliers of (velocity - minimum velocity) in positive and negative directions of mouse movement, respectively. Also see ChangeViscosity.
Friction
Parameters are in the range (-10000, +10000).
The parameters determine the friction coefficients, multipliers of (velocity - minimum velocity) in positive and negative directions of mouse movement, respectively.
Grid
Parameters are in the range (-10000, +10000).
The parameters determine the strengths of the node points in the horizontal and vertical directions, respectively, when moving over the grid. Also see ChangeStrength.
Inertia
Parameters are in the range (-10000, +10000).
The parameters determine the inertia coefficients, multipliers of (acceleration - minimum acceleration) in positive and negative directions of mouse movement, respectively.
Spring
Parameters are in the range (-10000, +10000).
The parameters determine the spring constants, the multipliers of mouse (displacement - deadband displacement) from spring center in positive and negative directions, respectively, along the spring axis/axes. Also see ChangeStiffness.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeCoefficientX, GetCoefficientNegativeY, GetCoefficientPositiveY.


ChangeDeadBand

Changes the deadband of an effect. The meaning of "deadband" is dependent on the type of the effect (see Supported Effects below).

boolean ChangeDeadBand(
    BSTR effectName,
    long lResourceReference,
    long lDeadBand
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lDeadBand
The new deadband value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Grid
Parameter is in pixels.
The parameter determines the center-to-center spacing of the grid lines. This sets both the horizontal and vertical spacing to the same value. For a grid, this method is the same as ChangeSpacing.
Spring
Parameter is in pixels.
The parameter determines the distance from the center of the spring over which the effect is not active (no forces are felt).

Remarks

This method assigns the same value to both the X- and Y- axes. To independently set these axes, use ChangeDeadBandX and ChangeDeadBandY.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeDeadBandX, ChangeDeadBandY, ChangeSpacing, GetDeadBandX, GetDeadBandY.


ChangeDeadBandX

Changes the X deadband of an effect. The meaning of "deadband" is dependent on the type of the effect (see Supported Effects below).

boolean ChangeDeadBandX(
    BSTR effectName,
    long lResourceReference,
    long lDeadBand
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lDeadBand
The new X deadband value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Grid
Parameter is in pixels.
The parameter determines the center-to-center spacing of the grid lines. This sets both the horizontal and vertical spacing to the same value. For a grid, this method is the same as ChangeSpacing.
Spring
Parameter is in pixels.
The parameter determines the distance from the center of the spring over which the effect is not active (no forces are felt).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDeadBand, ChangeDeadBandY, ChangeSpacing, GetDeadBandX, GetDeadBandY.


ChangeDeadBandY

Changes the Y deadband of an effect. The meaning of "deadband" is dependent on the type of the effect (see Supported Effects below).

boolean ChangeDeadBandY(
    BSTR effectName,
    long lResourceReference,
    long lDeadBand
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lDeadBand
The new Y deadband value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Grid
Parameter is in pixels.
The parameter determines the center-to-center spacing of the grid lines. This sets both the horizontal and vertical spacing to the same value. For a grid, this method is the same as ChangeSpacing.
Spring
Parameter is in pixels.
The parameter determines the distance from the center of the spring over which the effect is not active (no forces are felt).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDeadBand, ChangeDeadBandX, ChangeSpacing, GetDeadBandX, GetDeadBandY.


ChangeDirection

Changes the direction of an effect, or the axis along which the effect operates. The lDirectionX and lDirectionY parameters determine the direction vector in Cartesian coordinates. The magnitude of this vector is unimportant.

boolean ChangeDirection(
    BSTR effectName,
    long lResourceReference,
    long lDirectionX,
    long lDirectionY
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lDirectionX
The new direction's X-value, in pixels.
lDirectionY
The new direction's Y-value, in pixels.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
Specifies the direction of the constant force.
Damper
This method can only be used on a damper effect with a "Directional" axis. See MakeDamper2.
Ellipse
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the ellipse center point. See Remarks below.
Enclosure
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the enclosing rectangle's top left corner. See Remarks below.
Friction
This method can only be used on a friction effect with a "Directional" axis. See MakeFriction2.
Grid
This method can only be used on a grid effect with a "Directional" axis. See MakeGrid2.
Inertia
This method can only be used on an inertia effect with a "Directional" axis. See MakeInertia2.
Periodic
Specifies the axis along which the periodic effect plays.
Ramp
Specifies the direction of the ramp force.
Spring
This method can only be used on a spring with a "Directional" axis. See MakeSpring2.

Remarks

Note that the Cartesian (X, Y-axis) coordinate system in operation here has the Y-axis inverted compared with familiar Cartesian coordinates. On the screen, the positive X-direction is to the right, and the positive Y-direction is down. A vector of (1, 1) points approximately to the bottom right corner of the screen. A vector of (0, -1) points straight up.

Shape effects Ellipse and Enclosure do not behave the same way when rotated. Enclosures are rotated about their top left corners, and Ellipses are rotated about their center points. See the ChangeDirection Tutorial for a pictorial explanation.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeDirectionPolar, GetDirectionX, GetDirectionY, GetDirectionPoloar.


ChangeDirectionPolar

Changes the direction of an effect. The lAngle parameter determines the direction vector in polar coordinates.

boolean ChangeDirectionPolar(
    BSTR effectName,
    long lResourceReference,
    long lAngle
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lAngle
The new direction's angle, in hundredths of degrees (e.g. to turn an effect 45 degrees, pass an lAngle value of 4500).
.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
Specifies the direction of the constant force.
Damper
This method can only be used on a damper effect with a "Directional" axis. See MakeDamper2.
Ellipse
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the ellipse center point. See Remarks below.
Enclosure
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the enclosing rectangle's top left corner. See Remarks below.
Friction
This method can only be used on a friction effect with a "Directional" axis. See MakeFriction2.
Grid
This method can only be used on a grid effect with a "Directional" axis. See MakeGrid2.
Inertia
This method can only be used on an inertia effect with a "Directional" axis. See MakeInertia2.
Periodic
Specifies the axis along which the periodic effect plays.
Ramp
Specifies the direction of the ramp force.
Spring
This method can only be used on a spring with a "Directional" axis. See MakeSpring2.

Remarks

Note that the polar coordinate system in operation here is rotated 180 degrees and inverted compared with familiar polar coordinates. On the screen, an angle of 0 degrees points directly up, an angle of 90 degrees points to the right, an angle of 240 degrees points down and to the left. Angle measurement increases in a clockwise direction.

Shape effects Ellipse and Enclosure do not behave the same way when rotated. Enclosures are rotated about their top left corners, and Ellipses are rotated about their center points. See the ChangeDirection Tutorial for a pictorial explanation.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeDirection, GetDirectionX, GetDirectionY, GetDirectionPolar.


ChangeDuration

Changes the duration of an effect. The duration of an effect specifies how long the effect persists after being started or triggered.

boolean ChangeDuration(
    BSTR effectName,
    long lResourceReference,
    long lDuration
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lDuration
The new duration, in milliseconds.
Pass a negative number or 0xFFFFFFFF for an infinite duration.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Version 3.2.0.4: Passing a negative number for lDuration will not work. You must pass 0xFFFFFFFF.

Version 3.2.1.0: Works as documented.

See Also

GetDuration.


ChangeEnvelope

Changes the envelope (intensity variation with time) of an effect. An envelope has both an attack portion and a fade portion; each of these have an associated level and time. From the beginning of the effect, the force intensity, or level ramps from the attack level to the underlying effect's level over the attack time. At the end of the effect, the magnitude ramps from the effect's level to the fade level over the fade time.

boolean ChangeEnvelope(
    BSTR effectName,
    long lResourceReference,
    long lAttackLevel,
    long lAttackTime,
    long lFadeLevel,
    long lFadeTime
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lAttackLevel
The new attack level, with the range (-10000, +10000).
lAttackTime
The new attack time, in microseconds
lFadeLevel
The new fade level, with the range (-10000, +10000).
lFadeTime
The new fade time, in microseconds.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

The sum of the attack time and fade time must be less than or equal to the total duration of the effect being modified. An effect with infinite duration will not fade.

Note that attack and fade times are specified in microseconds (1/1,000,000 of a second), not milliseconds, like other durations. Very short attack and fade times tend to make an effect with an envelope feel essentially indistinguishable from the same effect without an envelope.

The attack level and fade level of the envelope can be either greater than or less than the basic level of the underlying effect.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

GetEnvelopeAttackLevel, GetEnvelopeAttackTime, GetEnvelopeFadeLevel, GetEnvelopeFadeTime.


ChangeGain

Changes the gain of an effect. The gain is an attenuation level for all forces within the effect - a higher gain value corresponds to less attenuation, and thus a stronger effect.

boolean ChangeGain(
    BSTR effectName,
    long lResourceReference,
    long lGain
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lGain
The new gain, with a range of (0, +10000). A value of 10000 indicates no attenuation.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

GetGain.


ChangeInsideEffect

Identifies the effect to be played inside the effect being changed. Inside effects are only supported for shape effects such as enclosures and ellipses (see Supported Effects below). An inside effect is an effect that is triggered (turned on) once the user enters its enclosing effect.

boolean ChangeInsideEffect(
    BSTR effectName,
    long lResourceReference,
    BSTR insideEffectName,
    long lInsideResourceReference
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
insideEffectName
The name of the new inside effect.
lInsideResourceReference
The resource reference for the new inside effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Ellipse
Enclosure

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


ChangeMagnitude

Changes the magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean ChangeMagnitude(
    BSTR effectName,
    long lResourceReference,
    long lMagnitude,
    long lMagnitude2
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lMagnitude
The first new magnitude value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lMagnitude2
The second new magnitude value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
The first parameter is in the range (-10000, +10000); the second parameter is ignored.
The first parameter (lMagnitude) determines the magnitude of the constant force; a negative magnitude exerts a force in the opposite direction. The ignored second parameter (lMagnitude2) should be set to zero.
Periodic
The first parameter is in the range (-10000, +10000); the second parameter is ignored.
The first parameter (lMagnitude) determines the amplitude of the periodic. The ignored second parameter (lMagnitude2) should be set to zero.
Ramp
The parameters are in the range (-10000, +10000).
The first parameter (lMagnitude) determines the ramp force at the beginning of the ramp. The second parameter (lMagnitude2) determines the ramp force at the end of the ramp. A negative magnitude exerts a force in the opposite direction.
Texture
The parameters are in the range (-10000, +10000).
The parameters determine the magnitude of force exerted at each bump when moving over the texture. The first parameter (lMagnitude) specifies the magnitude when moving across the texture in the positive direction along either axis. The second parameter (lMagnitude2) specifies the magnitude when moving in the negative direction along either axis.

Remarks

For a texture, this method assigns the same positive and negative values to both the X- and Y- axes. To independently set these axes, use ChangeMagnitudeX and ChangeMagnitudeY.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

GetMagnitude, GetMagnitude2, GetMagnitudeNegativeX, GetMagnitudeNegativeY, GetMagnitudePositiveX, GetMagnitudePositiveY.


ChangeMagnitudeX

Changes the X magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean ChangeMagnitudeX(
    BSTR effectName,
    long lResourceReference,
    long lPositiveMagnitude,
    long lNegativeMagnitude
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveMagnitude
The new positive-X magnitude value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeMagnitude
The new negative-X magnitude value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Texture
The parameters are in the range (-10000, +10000).
The parameters determine the magnitude of force exerted at each bump when moving over the texture. The first parameter (lPositiveMagnitude) specifies the magnitude when moving across the texture in the positive direction along either axis. The second parameter (lNegativeMagnitude) specifies the magnitude when moving in the negative direction along either axis.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeY, GetMagnitudeNegativeX, GetMagnitudeNegativeY, GetMagnitudePositiveX, GetMagnitudePositiveY.


ChangeMagnitudeY

Changes the Y magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean ChangeMagnitudeY(
    BSTR effectName,
    long lResourceReference,
    long lPositiveMagnitude,
    long lNegativeMagnitude
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveMagnitude
The new positive-Y magnitude value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeMagnitude
The new negative-Y magnitude value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Texture
The parameters are in the range (-10000, +10000).
The parameters determine the magnitude of force exerted at each bump when moving over the texture. The first parameter (lPositiveMagnitude) specifies the magnitude when moving across the texture in the positive direction along either axis. The second parameter (lNegativeMagnitude) specifies the magnitude when moving in the negative direction along either axis.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeX, GetMagnitudeNegativeX, GetMagnitudeNegativeY, GetMagnitudePositiveX, GetMagnitudePositiveY.


ChangeMinimum

Changes the minimum value of an effect. The meaning of "minimum" is dependent on the type of effect (see Supported Effects below).

boolean ChangeMinimum(
    BSTR effectName,
    long lResourceReference,
    long lMinimum
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lMinimum
The new minimum value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameter is in the range (0, +10000).
This parameter determines the minimum velocity necessary to activate the damping effect.
Friction
Parameter is in the range (0, +10000).
This parameter determines the minimum velocity necessary to activate the friction effect.
Inertia
Parameter is in the range (0, +10000).
This parameter determines the minimum acceleration necessary to activate the inertia effect.

Remarks

This method assigns the same value to both the X- and Y- axes. To independently set these axes, use ChangeMinimumX and ChangeMinimumY.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeMinimumX, ChangeMinimumY, GetMinimumX, GetMinimumY.


ChangeMinimumX

Changes the X minimum value of an effect. The meaning of "minimum" is dependent on the type of effect (see Supported Effects below).

boolean ChangeMinimumX(
    BSTR effectName,
    long lResourceReference,
    long lMinimum
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lMinimum
The new X minimum value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameter is in the range (0, +10000).
This parameter determines the minimum velocity necessary to activate the damping effect in the X direction.
Friction
Parameter is in the range (0, +10000).
This parameter determines the minimum velocity necessary to activate the friction effect in the X direction.
Inertia
Parameter is in the range (0, +10000).
This parameter determines the minimum acceleration necessary to activate the inertia effect in the X direction.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMinimum, ChangeMinimumY, GetMinimumX, GetMinimumY.


ChangeMinimumY

Changes the Y minimum value of an effect. The meaning of "minimum" is dependent on the type of effect (see Supported Effects below).

boolean ChangeMinimumY(
    BSTR effectName,
    long lResourceReference,
    long lMinimum
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lMinimum
The new Y minimum value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
Parameter is in the range (0, +10000).
This parameter determines the minimum velocity necessary to activate the damping effect in the Y direction.
Friction
Parameter is in the range (0, +10000).
This parameter determines the minimum velocity necessary to activate the friction effect in the Y direction.
Inertia
Parameter is in the range (0, +10000).
This parameter determines the minimum acceleration necessary to activate the inertia effect in the Y direction.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMinimum, ChangeMinimumX, GetMinimumX, GetMinimumY.


ChangeOffset

Changes the offset of an effect. The meaning of "offset" is dependent on the type of effect (see Supported Effects below).

boolean ChangeOffset(
    BSTR effectName,
    long lResourceReference,
    long lOffset,
    long lOffset2
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lOffset
The first new offset value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lOffset2
The second new offset value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Grid
Parameters are in pixels.
The parameters determine the distances from left and top edges of screen or enclosure at which the first grid effect (node) is felt. The first parameter (lOffset) specifies the left (X) value. The second parameter (lOffset2) specifies the top (Y) value. The default value of Offset set upon effect initialization is the mouse position on the screen when StartEffect is called. For a grid, this method is the same as ChangeCenter.
Periodic
The first parameter is in the range (-10000, +10000); the second parameter is ignored.
The first parameter (lOffset) determines the offset to the amplitude of the periodic. This is the magnitude of the force added to all forces exerted during the periodic effect. The ignored second parameter (lOffset2) should be set to zero.
Texture
Parameters are in pixels.
The parameters determine the distances from the left and top edges of the screen or enclosure at which the first texture effect (bump) is felt. The first parameter (lOffset) specifies the left (X) value. The second parameter (lOffset2) specifies the top (Y) value.

Remarks

For a grid, to acheive the IFC value of IMM_EFFECT_MOUSE_POS_AT_START, pass 0x7FFFFFFFF for both lOffset and lOffset2. Supplying these values will cause the assignment of the offset to be delayed until you call the StartEffect or StartEffect2 methods. At that time, the offset point will be set to the current position of the mouse cursor.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeCenter, GetOffset, GetOffset2.


ChangePeriod

Changes the period of a periodic effect. The period is the duration of a single waveform of the periodic, and is the multiplicative inverse of the periodic's frequency (period = 1/frequency).

boolean ChangePeriod(
    BSTR effectName,
    long lResourceReference,
    long lPeriod
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPeriod
The new period, in milliseconds.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Periodic

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

GetPeriod.


ChangePhase

Changes the phase of a periodic effect. The phase is the (temporal) offset to the period of the periodic. It determines where within the waveform the effect will begin playing.

boolean ChangePhase(
    BSTR effectName,
    long lResourceReference,
    long lPhase
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPhase
The new phase, in milliseconds.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Periodic

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

GetPhase.


ChangeRectangle

Changes the bounding rectangle of an effect. This is only applicable to shape effects such as enclosures and ellipses (see Supported Effects below).

boolean ChangeRectangle(
    BSTR effectName,
    long lResourceReference,
    long lLeft,
    long lTop,
    long lWidth,
    long lHeight
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lLeft
The new left coordinate of the bounding rectangle, in pixels.
lTop
The new top coordinate of the bounding rectangle, in pixels.
lWidth
The new width of the bounding rectangle, in pixels.
lHeight
The new height of the bounding rectangle, in pixels.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Ellipse
Enclosure

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeCenter, GetRectangleLeft, GetRectangleTop, GetRectangleWidth, GetRectangleHeight.


ChangeSaturation

Changes the saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean ChangeSaturation(
    BSTR effectName,
    long lResourceReference,
    long lSaturation,
    long lSaturation2
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lSaturation
The new saturation value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lSaturation2
The new saturation2 value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the damper. The first parameter (lSaturation) determines the maximum force in the positive direction. The second parameter (lSaturation2) determines the maximum force in the negative direction.
Ellipse
The first parameter is in the range (0, +10000); the second parameter is ignored.
The first parameter (lSaturation) determines the maximum force felt at the ellipse walls. The ignored second parameter (lSaturation2) should be set to zero.
Enclosure
The parameters are in the range (0, +10000).
The parameters determine the maximum forces felt at the enclosure walls. The first parameter (lSaturation) determines the maximum force at the top and bottom walls. The second parameter (lSaturation2) determines the maximum force at the left and right walls. If only the first parameter has a non-zero value, the first parameter determines the maximum force at all the walls, and the second parameter is ignored.
Friction
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the area exerting friction. The first parameter (lSaturation) determines the maximum force in the positive direction. The second parameter (lSaturation2) determines the maximum force in the negative direction.
Grid
The parameters are in the range (0, +10000).
The parameters determine the maximum force output felt at the node points of the grid. The first parameter (lSaturation) determines the maximum force in the horizontal direction. The second parameter (lSaturation2) determines the maximum force in the vertical direction.
Inertia
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the area exerting inertia. The first parameter (lSaturation) determines the maximum force in the positive direction. The second parameter (lSaturation2) determines the maximum force in the negative direction.
Spring
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to cursor displacement from the spring center. The first parameter (lSaturation) determines the maximum force output on the positive side. The second parameter (lSaturation2) determines the maximum force output on the negative side.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeSaturationX, ChangeSaturationY, GetSaturationNegativeX, GetSaturationNegativeY, GetSaturationPositiveX, GetSaturationPositiveY.


ChangeSaturationX

Changes the X saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean ChangeSaturationX(
    BSTR effectName,
    long lResourceReference,
    long lPositiveSaturation,
    long lNegativeSaturation
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveSaturation
The new positive-X saturation value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeSaturation
The new negative-X saturation value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the damper. The first parameter (lPositiveSaturation) determines the maximum force in the positive direction. The second parameter (lNegativeSaturation) determines the maximum force in the negative direction.
Friction
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the area exerting friction. The first parameter (lPositiveSaturation) determines the maximum force in the positive direction. The second parameter (lNegativeSaturation) determines the maximum force in the negative direction.
Grid
The parameters are in the range (0, +10000).
The parameters determine the maximum force output felt at the node points of the grid. The first parameter (lPositiveSaturation) determines the maximum force in the horizontal direction. The second parameter (lNegativeSaturation) determines the maximum force in the vertical direction.
Inertia
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the area exerting inertia. The first parameter (lPositiveSaturation) determines the maximum force in the positive direction. The second parameter (lNegativeSaturation) determines the maximum force in the negative direction.
Spring
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to cursor displacement from the spring center. The first parameter (lPositiveSaturation) determines the maximum force output on the positive side. The second parameter (lNegativeSaturation) determines the maximum force output on the negative side.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, ChangeSaturationY, GetSaturationNegativeX, GetSaturationNegativeY, GetSaturationPositiveX, GetSaturationPositiveY.


ChangeSaturationY

Changes the Y saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean ChangeSaturationY(
    BSTR effectName,
    long lResourceReference,
    long lPositiveSaturation,
    long lNegativeSaturation
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveSaturation
The new positive-Y saturation value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeSaturation
The new negative-Y saturation value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the damper. The first parameter (lPositiveSaturation) determines the maximum force in the positive direction. The second parameter (lNegativeSaturation) determines the maximum force in the negative direction.
Friction
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the area exerting friction. The first parameter (lPositiveSaturation) determines the maximum force in the positive direction. The second parameter (lNegativeSaturation) determines the maximum force in the negative direction.
Grid
The parameters are in the range (0, +10000).
The parameters determine the maximum force output felt at the node points of the grid. The first parameter (lPositiveSaturation) determines the maximum force in the horizontal direction. The second parameter (lNegativeSaturation) determines the maximum force in the vertical direction.
Inertia
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to motion across the area exerting inertia. The first parameter (lPositiveSaturation) determines the maximum force in the positive direction. The second parameter (lNegativeSaturation) determines the maximum force in the negative direction.
Spring
The parameters are in the range (0, +10000).
The parameters determine the maximum force output in response to cursor displacement from the spring center. The first parameter (lPositiveSaturation) determines the maximum force output on the positive side. The second parameter (lNegativeSaturation) determines the maximum force output on the negative side.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, ChangeSaturationX, GetSaturationNegativeX, GetSaturationNegativeY, GetSaturationPositiveX, GetSaturationPositiveY.


ChangeSpacing

Changes the spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean ChangeSpacing(
    BSTR effectName,
    long lResourceReference,
    long lHorizontalSpacing,
    long lVerticalSpacing
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lSpacing
The first new spacing value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lSpacing2
The second new spacing value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Grid
Parameters are in pixels.
The parameters specify the center-to-center spacing of the grid lines. The first parameter (lSpacing) specifies the horizontal spacing. The second parameter (lSpacing2) specifies the vertical spacing.
Texture
Parameters are in pixels.
The parameters specify the center-to-center spacings of the texture bumps in different directions of travel. The first parameter (lSpacing) specifies the spacing in the positive direction along each axis. The second parameter (lSpacing2) specifies the spacing in the negative direction along each axis.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeSpacingX, ChangeSpacingY, GetSpacingX, GetSpacingY, GetSpacingNegativeX, GetSpacingNegativeY, GetSpacingPositiveX, GetSpacingPositiveY.


ChangeSpacingX

Changes the X spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean ChangeSpacingX(
    BSTR effectName,
    long lResourceReference,
    long lHorizontalSpacing,
    long lVerticalSpacing
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveSpacing
The new positive-X spacing value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeSpacing
The new negative-X spacing value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Texture
Parameters are in pixels.
The parameters specify the center-to-center spacings of the texture bumps in different directions of travel. The first parameter (lPositiveSpacing) specifies the spacing in the positive direction along each axis. The second parameter (lNegativeSpacing) specifies the spacing in the negative direction along each axis.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacing, ChangeSpacingY, GetSpacingX, GetSpacingY, GetSpacingNegativeX, GetSpacingNegativeY, GetSpacingPositiveX, GetSpacingPositiveY.


ChangeSpacingY

Changes the Y spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean ChangeSpacingX(
    BSTR effectName,
    long lResourceReference,
    long lHorizontalSpacing,
    long lVerticalSpacing
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveSpacing
The new positive-Y spacing value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeSpacing
The new negative-Y spacing value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Texture
Parameters are in pixels.
The parameters specify the center-to-center spacings of the texture bumps in different directions of travel. The first parameter (lPositiveSpacing) specifies the spacing in the positive direction along each axis. The second parameter (lNegativeSpacing) specifies the spacing in the negative direction along each axis.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacing, ChangeSpacingX, GetSpacingX, GetSpacingY, GetSpacingNegativeX, GetSpacingNegativeY, GetSpacingPositiveX, GetSpacingPositiveY.


ChangeStartDelay

Changes the start delay of an effect. The start delay of an effect specifies the amount of time to delay the playing of an effect after it is started with StartEffect.

boolean ChangeStartDelay(
    BSTR effectName,
    long lResourceReference,
    long lStartDelay
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lStartDelay
The new start delay, in milliseconds.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

GetStartDelay.


ChangeStiffness

Changes the stiffness of an effect. The meaning of "stiffness" is dependent on the type of the effect (see Supported Effects below).

boolean ChangeStiffness(
    BSTR effectName,
    long lResourceReference,
    long lStiffness,
    long lStiffness2
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lStiffness
The first new stiffness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lStiffness2
The second new stiffness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Ellipse
The first parameter is in the range (-10000, +10000); the second parameter is ignored.
The first parameter (lStiffness) specifies the stiffness of all the ellipse walls. Negative and positive values of stiffness cause a variety of different behaviors when combined with different stiffness mask values. The ignored second parameter (lStiffness2) should be set to zero. Also see ChangeStiffnessMask.
Enclosure
The parameters are in the range (-10000, +10000)
The parameters specify the stiffness of the enclosure walls. The first parameter (lStiffness) determines the stiffness of the top and bottom walls. The second parameter (lStiffness2) determines the stiffness of the left and right walls. If only the first parameter has a non-zero value, the first parameter determines the maximum force at all the enclosure walls, and the second parameter is ignored. Negative and positive values of stiffness cause a variety of different behaviors when combined with different stiffness mask values. Also see ChangeStiffnessMask.
Spring
The first parameter is in the range (-10000, +10000); the second parameter is ignored.
The first parameter (lStiffness) specifies a single value of the spring coefficient for both the positive and negative directions of cursor displacement from the spring center. Use ChangeCoefficient to set the positive and negative spring coefficients to different values. The ignored second parameter (lStiffness2) should be set to zero.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeCoefficient, ChangeStiffnessMask, GetCoefficientNegativeX, GetCoefficientNegativeY, GetCoefficientPositiveX, GetCoefficientPositiveY, GetStiffness, GetStiffness2.


ChangeStiffnessMask

Changes the stiffness mask of an effect. A stiffness mask specifies which walls of a shape are active (exerting forces). This method applies only to enclosures and ellipses (see Supported Effects below).

boolean ChangeStiffnessMask(
    BSTR effectName,
    long lResourceReference,
    long lStiffnessMask
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lStiffnessMask
The mask to specify which walls are active. See Supported Effects below to see what values to pass for a particular effect.

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Ellipse
The parameter is a mask created by OR-ing the flags below.
Ellipse Clipping Masks
Flag

Any inner wall

0x66

Any outer wall

0x99

Any wall

0xFF

Enclosure
The parameter is a mask created by OR-ing the flags below.
Enclosure Clipping Masks
Flag

None

0x00

Outer left wall

0x01

Inner left wall

0x02

Inner right wall

0x04

Outer right wall

0x08

Outer top wall

0x10

Inner top wall

0x20

Inner bottom wall

0x40

Outer bottom wall

0x80

Inner any wall

0x66

Outer any wall

0x99

Any wall

0xFF

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeClippingMask, GetStiffnessMask.


ChangeStrength

Changes the strengths of the node points in the horizontal and vertical directions when moving over a grid effect. This method is the same as ChangeCoefficient.

boolean ChangeStrength(
    BSTR effectName,
    long lResourceReference,
    long lHorizontalNodeStrength,
    long lVerticalNodeStrength
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lHorizontalNodeStrength
The new horizontal node strength value, having a range of (-10000, +10000).
lVerticalNodeStrength
The new vertical node strength value, having a range of (-10000, +10000).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Grid

Remarks

For a grid, this method is the same as ChangeCoefficient.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeCoefficient, ChangeCoefficientX, ChangeCoefficientY.


ChangeThickness

Changes the thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean ChangeThickness(
    BSTR effectName,
    long lResourceReference,
    long lThickness,
    long lThickness2
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lThickness
The first new Thickness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lThickness2
The second new Thickness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Ellipse
The first parameter is in pixels; the second parameter is ignored.
The first parameter (lThickness) specifies the width of all the ellipse walls. The ignored second parameter (lThickness2) should be set to zero.
Enclosure
The parameters are in pixels
The parameters specify the width of the enclosure walls. The first parameter (lThickness) determines the width of the top and bottom walls. The second parameter (lThickness2) determines the width of the left and right walls. If only the first parameter has a non-zero value, the first parameter determines the width of all the enclosure walls, and the second parameter is ignored.
Texture
The parameters are in the range (-10000, +10000).
The parameters specify the widths of the bumps in the texture effect. The first parameter (lThickness) determines the bump width in the positive direction of motion along either axis. The second parameter (lThickness2) determines the bump width in the negative direction.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeThicknessX, ChangeThicknessY, GetThickness, GetThickness2, GetThicknessNegativeX,GetThicknessNegativeY, GetThicknessPositiveX, GetThicknessPositiveY.


ChangeThicknessX

Changes the X thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean ChangeThicknessX(
    BSTR effectName,
    long lResourceReference,
    long lPositiveThickness,
    long lNegativeThickness
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveThickness
The first new positive-X thickness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeThickness
The second new negative-X hickness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Texture
The parameters are in the range (-10000, +10000).
The parameters specify the widths of the bumps in the texture effect. The first parameter (lPositiveThickness) determines the bump width in the positive-X direction of motion (to the right). The second parameter (lNegativeThickness) determines the bump width in the negative-X direction (to the left).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, ChangeThicknessY, GetThicknessPositiveX, GetThicknessNegativeX.


ChangeThicknessY

Changes the Y thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean ChangeThicknessY(
    BSTR effectName,
    long lResourceReference,
    long lPositiveThickness,
    long lNegativeThickness
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lPositiveThickness
The first new positive-Y thickness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).
lNegativeThickness
The second new negative-Y hickness value. The meaning of this value is dependent on the effect being changed (see Supported Effects below).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Texture
The parameters are in the range (-10000, +10000).
The parameters specify the widths of the bumps in the texture effect. The first parameter (lPositiveThickness) determines the bump width in the positive-Y direction of motion (downwards). The second parameter (lNegativeThickness) determines the bump width in the negative-Y direction (upwards).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, ChangeThicknessX, GetThicknessPositiveY, GetThicknessNegativeY.


ChangeViscosity

Changes the viscosity (damping coefficient) of a damper effect. The force of a damper is calculated by multiplying the viscosity by (velocity - minumum velocity), provided the user is moving faster than minumum velocity. Dampers can have both positive and negative viscosities (damping coefficients); using ChangeViscosity sets these coeffients to be equal. Use ChangeCoefficient to set them to different values.

boolean ChangeViscosity(
    BSTR effectName,
    long lResourceReference,
    long lViscosity
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lViscosity
The new viscosity value, having a range of (-10000, +10000).

Return Values

Returns TRUE if successful, FALSE otherwise. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below), FALSE will be returned.

Supported Effects

Damper

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

ChangeCoefficient , GetCoefficientNegativeX, GetCoefficientNegativeY, GetCoefficientPositiveX, GetCoefficientPositiveY.


Device Management Methods

The following "Device Management" methods allow developers to query information about the acquired device.

Device Management Methods
GetCursorPosX
GetCursorPosY
GetDeviceFlag
GetDevicePosX
GetDevicePosY
GetDeviceProductName
GetDeviceType
GetDeviceTypeName
GetDeviceTechnology
GetDeviceTechnologyName
GetScreenPosX
GetScreenPosY
TouchSenseDeviceAttached


GetCursorPosX

Returns the X-position of the system cursor in screen coordinates.

long GetCursorPosX();

Parameters

None.

Return Values

Returns the X-position of the system cursor in screen coordinates.

Remarks

The minimum screen coordinates are (0, 0). The maximum screen coordinates are dependent on the user's display settings.

For a cursor-control device, this method is identical to GetScreenPosX. However, for non-cursor-control devices, this method returns the system cursor's position, not the device's position.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetCursorPosY, GetScreenPosX, GetScreenPosY, GetDevicePosX, GetDevicePosY.


GetCursorPosX

Immersion Web Plugin Reference

GetCursorPosY

Returns the Y-position of the system cursor in screen coordinates.

long GetCursorPosY();

Parameters

None.

Return Values

Returns the Y-position of the system cursor in screen coordinates.

Remarks

The minimum screen coordinates are (0, 0). The maximum screen coordinates are dependent on the user's display settings.

For a cursor-control device, this method is identical to GetScreenPosY. However, for non-cursor-control devices, this method returns the system cursor's position, not the device's position.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetCursorPosX, GetScreenPosX, GetScreenPosY, GetDevicePosX, GetDevicePosY.


GetDeviceFlag

Returns the DeviceFlag property of the Immersion Web Plugin. The DeviceFlag determines what devices can be used by the Immersion Web Plugin. See the Remarks section below.

long GetDeviceFlag();

Parameters

None.

Return Values

Returns the DeviceFlag property. It can be one of the following values:

Name | Value | Meaning
dfForbidDXDevice | 0 | The Plugin can only acquire a TouchSense mouse.
dfAllowDXDevice | 1 | The Plugin can acquire a TouchSense mouse or DirectX device, but will look for a TouchSense mouse first.
dfPreferDXDevice | 2 | The Plugin can acquire a TouchSense mouse or DirectX device, but will look for a DirectX device first.
dfRequireDXDevice | 3 | The Plugin can only acquire a DirectX device.

Remarks

In Internet Explorer and Netscape, you must use the DeviceFlag value. The DeviceFlag name can only be used by certain applications such as Microsoft Visual Basic and Macromedia Director.

The DeviceFlag defaults to 0 (dfForbidDXDevice).

This property cannot be set at run-time, however it can be assigned during design-time.

With Internet Explorer, it can be set via the PARAM tag: <PARAM name="DeviceFlag" value="1">.

With Netscape, it can be set via the DeviceFlag property in the EMBED tag:
  <EMBED TYPE="application/x-Immersion-Web-Plugin"
  NAME="ImmWeb" HEIGHT="0" WIDTH="0" SRC="myfile.txt"
  DEVICEFLAG="3">.

Other tools have their own way for setting design-time parameters.

For further details, consult Using TouchSense Gaming Devices With the Immersion Web Plugin.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

Nothing.


GetDevicePosX

Returns the X-position of the Immersion Web Plugin's acquired TouchSense device in device coordinates.

long GetDevicePosX();

Parameters

None.

Return Values

Returns the X-position of the Immersion Web Plugin's acquired TouchSense device in device coordinates.

Remarks

The minimum device coordinates are (-10000, -10000) which is upper left. The maximum device coordinates are (10000, 10000) which is lower right.

If the device was not acquired through DirectX, its native coordinate system is not the same as device coordinates. Thus, a conversion between screen and device coordinate systems is performed by the Plugin. This conversion is unreliable on multi-monitor systems.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

GetScreenPosX, GetScreenPosY, GetDevicePosY.


GetDevicePosY

Returns the Y-position of the Immersion Web Plugin's acquired TouchSense device in device coordinates.

long GetDevicePosX();

Parameters

None.

Return Values

Returns the Y-position of the Immersion Web Plugin's acquired TouchSense device in device coordinates.

Remarks

The minimum device coordinates are (-10000, -10000) which is upper left. The maximum device coordinates are (10000, 10000) which is lower right.

If the device was not acquired through DirectX, its native coordinate system is not the same as device coordinates. Thus, a conversion between screen and device coordinate systems is performed by the Plugin. This conversion is unreliable on multi-monitor systems.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

GetScreenPosX, GetScreenPosY, GetDevicePosX.


GetDeviceProductName

Returns the English product name of the attached device, if available.

BSTR GetDeviceProductName();

Parameters

None.

Return Values

Returns the English product name of the attached device. If not available, returns an empty string.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

Nothing.


GetDeviceType

Returns the type of the attached device. See the Return Values section below.

long GetDeviceType();

Parameters

None.

Return Values

Returns the type of the attached device. It can be one of the following values:

Name | Value | Meaning
dtOther | 0 | Other Device
dtJoystick | 1 | Joystick
dtWheel | 2 | Wheel
dtGamepad | 3 | Gamepad
dtAbsoluteMouse | 4 | Absolute Mouse
dtRelativeMouse | 5 | Relative Mouse

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetDeviceTechnology, GetDeviceTechnologyName, GetDeviceTypeName.


GetDeviceTypeName

Returns the English name of the type of the attached device.

BSTR GetDeviceTypeName();

Parameters

None.

Return Values

Returns the English name of the type of the attached device.

Remarks

This method is used for informational purposes, and its return values are subject to chage. To check the device's type and to perform an action based on this, use GetDeviceType. It is the safest choice for backward compatibility.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetDeviceTechnology, GetDeviceTechnologyName, GetDeviceType.


GetDeviceTechnology

Returns the type of Immersion TouchSense technology used by the attached device. See the Return Values section below.

long GetDeviceTechnology();

Parameters

None.

Return Values

Returns the type of Immersion TouchSense technology. It can be one of the following values:

Name | Value | Meaning
ttOther | 0 | Other Technology
ttVibro | 1 | Vibrotactile
ttIHD | 2 | Inertial Harmonic
ttFullFF | 3 | Full Force-Feedback

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetDeviceTechnologyName, GetDeviceType, GetDeviceTypeName.


GetDeviceTechnologyName

Returns the English name of Immersion TouchSense technology used by the attached device.

BSTR GetDeviceTechnologyName();

Parameters

None.

Return Values

Returns the English name of Immersion TouchSense technology used by the attached device.

Remarks

This method is used for informational purposes, and its return values are subject to chage. To check the device's technology and to perform an action based on this, use GetDeviceTechnology. It is the safest choice for backward compatibility.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetDeviceTechnology, GetDeviceType, GetDeviceTypeName .


GetScreenPosX

Returns the X-position of the Immersion Web Plugin's acquired TouchSense device in screen coordinates.

long GetScreenPosX();

Parameters

None.

Return Values

Returns the X-position of the Immersion Web Plugin's acquired TouchSense device in screen coordinates.

Remarks

The minimum screen coordinates are (0, 0). The maximum screen coordinates are dependent on the user's display settings.

If the device was acquired through DirectX, its native coordinate system is not the same as screen coordinates. Thus, a conversion between device and screen coordinate systems is performed by the Plugin. This conversion is unreliable on multi-monitor systems.

For a cursor-control device, this method is identical to GetCursorPosX. However, for non-cursor-control devices, this method returns the device's position in screen coordinates, not the system cursor's position.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

GetScreenPosY, GetCursorPosX, GetCursorPosY, GetDevicePosX, GetDevicePosY.


GetScreenPosY

Returns the Y-position of the Immersion Web Plugin's acquired TouchSense device in screen coordinates.

long GetScreenPosY();

Parameters

None.

Return Values

Returns the Y-position of the Immersion Web Plugin's acquired TouchSense device in screen coordinates.

Remarks

The minimum screen coordinates are (0, 0). The maximum screen coordinates are dependent on the user's display settings.

If the device was acquired through DirectX, its native coordinate system is not the same as screen coordinates. Thus, a conversion between device and screen coordinate systems is performed by the Plugin. This conversion is unreliable on multi-monitor systems.

For a cursor-control device, this method is identical to GetCursorPosY. However, for non-cursor-control devices, this method returns the device's position in screen coordinates, not the system cursor's position.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

GetScreenPosX, GetCursorPosX, GetCursorPosY, GetDevicePosX, GetDevicePosY.


TouchSenseDeviceAttached

Determines whether a TouchSense device is attached to the system and was properly initialized.

boolean TouchSenseDeviceAttached();

Parameters

None.

Return Values

Returns TRUE if a TouchSense device is attached to the system and was properly acquired and initialized. Otherwise, this method returns FALSE.

Remarks

If a TouchSense device was properly and acquired and subsequently removed, this method will still return TRUE. This will be corrected in a future version of the control.

Plugin Version Compatibility

Version 3.2.0.4: This control currently only supports TouchSense mice (such as the Logitech Wingman Force-Feedback Mouse). Thus, this control will only return TRUE if a TouchSense mouse is connected; it will fail for joysticks, steering wheels, etc

Version 3.2.1.0: Works for all TouchSense devices supported by IFC and allowed by the DeviceFlag.

See Also

GetDeviceFlag.


Effect Play and Management Methods

The following "Effect Play and Management" methods allow developers to start and stop effects, as well as query information about them.

Effect Play and Management Methods
EffectExists
EffectSupportsChange
EffectSupportsGet
GetLastError
GetNameOfEffect
GetNumberOfEffects
OpenForceResource
StartEffect
StartEffect2
StopEffect
StopEffects


EffectExists

Returns TRUE if the specified effect exists in the specified resource.

boolean EffectExists(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to look for.
lResourceReference
The resource reference to look for this effect in, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns TRUE if the specified effect exists, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

EffectSupportsChange, EffectSupportsGet.


EffectSupportsChange

Checks whether a specific Change property method is supported by the specified effect.

boolean EffectSupportsChange(
    BSTR effectName,
    long lResourceReference,
    BSTR propertyName
);

Parameters

effectName
The name of the effect to check.
lResourceReference
The resource reference of this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
propertyName
The name of the property to check (see Remarks below).
This name is not case sensitive.

Return Values

Returns TRUE if the specified effect supports the a Change method for the specified property. Returns FALSE if the change is not supported, if the effect does not exist, or if the property name is invalid.

Remarks

Valid property names are below. These names are not case sensitive.

Valid propertyName Values
"axis"
"center"
"clippingMask"
"coefficient"
"coefficientXY"
"deadband"
"deadbandXY"
"direction"
"directionpolar"
"duration"
"envelope"
"insideEffect"
"magnitude"
"magnitudeXY"
"minimum"
"minimumXY"
"offset"
"period"
"phase"
"rectangle"
"saturation"
"saturationXY"
"spacing"
"spacingXY"
"startDelay"
"stiffness"
"stiffnessMask"
"strength"
"thickness"
"viscosity"
"waveform"

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

EffectExists, EffectSupportsGet.


EffectSupportsGet

Checks whether a specific Get property method is supported by the specified effect.

boolean EffectSupportsGet(
    BSTR effectName,
    long lResourceReference,
    BSTR propertyName
);

Parameters

effectName
The name of the effect to check.
lResourceReference
The resource reference of this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
propertyName
The name of the property to check (see Remarks below).
This name is not case sensitive.

Return Values

Returns TRUE if the specified effect supports the a Get method for the specified property. Returns FALSE if the change is not supported, if the effect does not exist, or if the property name is invalid.

Remarks

Valid property names are below. These names are not case sensitive.

Valid propertyName Values
"axis"
"center"
"clippingMask"
"coefficient"
"coefficientXY"
"deadband"
"deadbandXY"
"direction"
"directionpolar"
"duration"
"envelope"
"insideEffect"
"magnitude"
"magnitudeXY"
"minimum"
"minimumXY"
"offset"
"period"
"phase"
"rectangle"
"saturation"
"saturationXY"
"spacing"
"spacingXY"
"startDelay"
"stiffness"
"stiffnessMask"
"strength"
"thickness"
"viscosity"
"waveform"

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

EffectExists, EffectSupportsChange.


GetLastError

Returns the LastError property of the Immersion Web Plugin. When a Plugin method fails due to IFC, LastError holds the IFC error code.

long GetLastError();

Parameters

None.

Return Values

Returns the LastError property.

Remarks

The value of LastError is only valid after a Plugin method fails due to an IFC error and before another Plugin method is invoked.

This property is intended for debugging purposes.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

Nothing.


GetNameOfEffect

Returns the name of an effect in a specified resource.

BSTR GetNameOfEffect(
    long lEffectNumber,
    long lResourceReference
);

Parameters

lEffectNumber
The zero-based index of the effect whose name you wish to query the name. Valid numbers are between 0 and GetNumberOfEffects()-1.
lResourceReference
The reference number for the resource you wish to query, as returned by OpenForceResource. Pass -1 for the global resource which stores effects created with the "Make" method.

Return Values

Returns the name of specified effect in the specified resource. Returns a NULL string if the effect number is out of range or if the resource reference is invalid.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

GetNumberOfEffects, Making Effects with the Immersion Web Plugin


GetNumberOfEffects

Returns the number of effects in the specified resource.

long GetNumberOfEffects(
    long lResourceReference
);

Parameters

lResourceReference
The reference number for the resource you wish to query, as returned by OpenForceResource. Pass -1 for the global resource which stores effects created with the "Make" method.

Return Values

Returns the number of effects in the specified resource. Returns -1 if the resource is not valid.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

GetNameOfEffect, Making Effects with the Immersion Web Plugin


OpenForceResource

Downloads a force resource file, creates a project for it, and returns a zero-based reference number for the project.

long OpenForceResource(
    BSTR url
);

Parameters

url
A string containing the uniform resource locator (URL) of the .IFR file. This parameter can be a relative URL (../forces/effect.ifr) or an absolute URL (http://www.immersion.com/forces/effect.ifr).

Return Values

If successful, this method returns a zero-based reference number for the project. Use this reference when calling StartEffect, StartEffect2, StopEffect, StopEffects, or any of the Change methods.

If OpenForceResource fails, it returns one of the following negative error codes:

Meaning | Error Code
Cannot find or open the URL | -2
Cannot allocate the project | -3
No device was found | -4
Empty URL passed | -101

Remarks

The downloading of the force resource file is subject to browser security restrictions.

Although relative URLs can be used, they only work reliably within Netscape Navigator or Internet Explorer. In other applications, it is recommended that you use absolute URLs.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


StartEffect

Starts an effect. See also StartEffect2.

boolean StartEffect(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to start.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


StartEffect2

Starts an effect with particular options. See also StartEffect.

boolean StartEffect2(
    BSTR effectName,
    long lResourceReference,
    long lIterations,
    long lFlags
);

Parameters

effectName
The name of the effect to start.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.
lIterations
The number of times to repeat the effect. Passing a negative number or 0xFFFFFFFF will repeat the effect an infinite number of times.
lFlags
Modifies how the effect is started. The flag is produced by OR-ing the following flags:
Meaning | Flag
Normal | 0
"Solo": Stop all playing effects when starting this one | 1
"No Download": creates the effect but doesn't play it | 0x80000000
Combination of "Solo" and "No Download" | 0x80000001

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Version 3.2.0.4: Passing a negative number for lIterations will not work. You must pass 0xFFFFFFFF.

Version 3.2.1.0: Works as documented.

See Also

Nothing.


StopEffect

Stops an effect. See also StopEffects.

boolean StopEffect(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to stop.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

StopEffects


StopEffects

Immediately stops playing all effects in all projects. See also StopEffect.

boolean StopEffects();

Parameters

None.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

StopEffect


Get Effect Property Methods

The following "Get Property" methods allow developers to query the properties of an effect. You can query whether an effect supports getting a particular property by calling EffectSupportsGet.

Get Property Methods
GetEffectTypeName | GetEnvelopeAttackLevel | GetPeriod | GetSpacingPositiveY
GetAxis | GetEnvelopeAttackTime | GetPhase | GetSpacingX
GetCenterX | GetEnvelopeFadeLevel | GetRectangleLeft | GetSpacingY
GetCenterY | GetEnvelopeFadeTime | GetRectangleTop | GetStartDelay
GetClippingMask | GetGain | GetRectangleWidth | GetStiffness
GetCoefficientNegativeX | GetMagnitude | GetRectangleHeight | GetStiffness2
GetCoefficientNegativeY | GetMagnitude2 | GetSaturation | GetStiffnessMask
GetCoefficientPositiveX | GetMagnitudeNegativeX | GetSaturation2 | GetThickness
GetCoefficientPositiveY | GetMagnitudeNegativeY | GetSaturationNegativeX | GetThickness2
GetDeadBandX | GetMagnitudePositiveX | GetSaturationNegativeY | GetThicknessNegativeX
GetDeadBandY | GetMagnitudePositiveY | GetSaturationPositiveX | GetThicknessNegativeY
GetDirectionX | GetMinimumX | GetSaturationPositiveY | GetThicknessPositiveX
GetDirectionY | GetMinimumY | GetSpacingNegativeX | GetThicknessPositiveY
GetDirectionPolar | GetOffset | GetSpacingNegativeY | GetWaveform
GetDuration | GetOffset2 | GetSpacingPositiveX |


GetAxis

Returns the axis type of an effect.

long GetAxis(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the axis type of an effect. Possible return values are:

Name | Value | Meaning
axDirectional | 0 | Directional
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Supported Effects

Damper
Friction
Grid
Inertia
Spring

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

MakeDamper, MakeDamper2, MakeFriction, MakeFriction2, MakeGrid, MakeGrid2, MakeInertia, MakeInertia2, MakeSpring, MakeSpring2


GetCenterX

Returns the X-coordinate of the the center of an effect. The meaning of "center" is dependent on the type of the effect being changed (see Supported Effects below).

long GetCenterX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the X-coordinate of the center of an effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (-10000, +10000).
The result determines the offset to the minimum velocity at which opposing force is applied in x-direction.
Ellipse
Result is in pixels.
The result determines the location of ellipse center from the top-left corner of the screen.
Enclosure
Result is in pixels.
The result determines the location of enclosure center from the top-left corner of the screen.
Friction
Result is in the range (-10000, +10000).
The result determines the offsets to the minimum velocity at which opposing force is applied in x-direction
Grid
Result is in pixels.
The result determines the distances from left and top edges of screen or enclosure at which first grid effect (node) is felt.
Inertia
Result is in the range (-10000, +10000).
The result determines the offsets to the minimum acceleration at which opposing force is applied in x- direction.
Spring
Result is in pixels.
The result determines the distance of the spring center from the top-left corner of the screen.

Remarks

When getting the center of a single-axis effect, only one of GetCenterX or GetCenterY will suceed — the one that corresponds to the axis of the condition. The other method will return 0xDEAD.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetCenterY, ChangeCenter.


GetCenterY

Returns the Y-coordinate of the the center of an effect. The meaning of "center" is dependent on the type of the effect being changed (see Supported Effects below).

long GetCenterY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the Y-coordinate of the center of an effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (-10000, +10000).
The result determines the offset to the minimum velocity at which opposing force is applied in x-direction.
Ellipse
Result is in pixels.
The result determines the location of ellipse center from the top-left corner of the screen.
Enclosure
Result is in pixels.
The result determines the location of enclosure center from the top-left corner of the screen.
Friction
Result is in the range (-10000, +10000).
The result determines the offsets to the minimum velocity at which opposing force is applied in x-direction
Grid
Result is in pixels.
The result determines the distances from left and top edges of screen or enclosure at which first grid effect (node) is felt.
Inertia
Result is in the range (-10000, +10000).
The result determines the offsets to the minimum acceleration at which opposing force is applied in x- direction.
Spring
Result is in pixels.
The result determines the distance of the spring center from the top-left corner of the screen.

Remarks

When getting the center of a single-axis effect, only one of GetCenterX or GetCenterY will suceed — the one that corresponds to the axis of the condition. The other method will return 0xDEAD.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetCenterX, ChangeCenter.


GetClippingMask

Gets the clipping mask of an effect. A clipping mask specifies which walls of a shape have cursor clipping (a visual effect giving the illusion of wall impenetrability) active. This method applies only to enclosures and ellipses (see Supported Effects below).

long GetClippingMask(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the clipping mask of the effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Ellipse
The result is a mask created by OR-ing the flags below.
Ellipse Clipping Masks
Flag

Any inner wall

0x66

Any outer wall

0x99

Any wall

0xFF
Enclosure
The result is a mask created by OR-ing the flags below.
Enclosure Clipping Masks
Flag

None

0x00

Outer left wall

0x01

Inner left wall

0x02

Inner right wall

0x04

Outer right wall

0x08

Outer top wall

0x10

Inner top wall

0x20

Inner bottom wall

0x40

Outer bottom wall

0x80

Inner any wall

0x66

Outer any wall

0x99

Any wall

0xFF

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeClippingMask.


GetCoefficientNegativeX

Gets the negative-X coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean GetCoefficientNegativeX(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative-X coefficient of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (-10000, +10000).
The result determines the negative X damping coefficient, the multiplier of (velocity - minimum velocity) in the negative X-direction of mouse movement. Also see ChangeViscosity.
Friction
Result is in the range (-10000, +10000).
The result determines the negative X friction coefficient, the multiplier of (velocity - minimum velocity) in the negative X-direction of mouse movement.
Grid
Result is in the range (-10000, +10000).
The result determines the strength of the node points in the horizontal directions, respectively, when moving left over the grid. Also see ChangeStrength.
Inertia
Result is in the range (-10000, +10000).
The result determines the negative X inertia coefficient, the multiplier of (acceleration - minimum acceleration) in negative X-direction of mouse movement.
Spring
Result is in the range (-10000, +10000).
The result determines the negative X spring constant, the multiplier of (displacement - deadband displacement) from spring center in the negative X-direction along the spring axis. Also see ChangeStiffness.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeCoefficientX, GetCoefficientPositiveX, GetCoefficientPositiveY, GetCoefficientNegativeY.


GetCoefficientNegativeY

Gets the negative-Y coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean GetCoefficientPositiveY(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative-Y coefficient of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (-10000, +10000).
The result determines the negative Y damping coefficient, the multiplier of (velocity - minimum velocity) in the negative Y-direction of mouse movement. Also see ChangeViscosity.
Friction
Result is in the range (-10000, +10000).
The result determines the negative Y friction coefficient, the multiplier of (velocity - minimum velocity) in the negative Y-direction of mouse movement.
Grid
Result is in the range (-10000, +10000).
The result determines the strength of the node points in the vertical directions, respectively, when moving up over the grid. Also see ChangeStrength.
Inertia
Result is in the range (-10000, +10000).
The result determines the negative Y inertia coefficient, the multiplier of (acceleration - minimum acceleration) in negative Y-direction of mouse movement.
Spring
Result is in the range (-10000, +10000).
The result determines the negative Y spring constant, the multiplier of (displacement - deadband displacement) from spring center in the negative Y-direction along the spring axis. Also see GetStiffness.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeCoefficientX, GetCoefficientPositiveX, GetCoefficientPositiveY, GetCoefficientNegativeX.


GetCoefficientPositiveX

Gets the positive-X coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean GetCoefficientPositiveX(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive-X coefficient of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (-10000, +10000).
The result determines the positive X damping coefficient, the multiplier of (velocity - minimum velocity) in the positive X-direction of mouse movement. Also see ChangeViscosity.
Friction
Result is in the range (-10000, +10000).
The result determines the positive X friction coefficient, the multiplier of (velocity - minimum velocity) in the positive X-direction of mouse movement.
Grid
Result is in the range (-10000, +10000).
The result determines the strength of the node points in the horizontal directions, respectively, when moving right over the grid. Also see ChangeStrength.
Inertia
Result is in the range (-10000, +10000).
The result determines the positive X inertia coefficient, the multiplier of (acceleration - minimum acceleration) in positive X-direction of mouse movement.
Spring
Result is in the range (-10000, +10000).
The result determines the positive X spring constant, the multiplier of (displacement - deadband displacement) from spring center in the positive X-direction along the spring axis. Also see ChangeStiffness.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeCoefficientX, GetCoefficientPositiveY, GetCoefficientNegativeX, GetCoefficientNegativeY.


GetCoefficientPositiveY

Gets the positive-Y coefficient of an effect. The meaning of "coefficient" is dependent on the type of effect (see Supported Effects below).

boolean GetCoefficientPositiveY(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive-Y coefficient of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (-10000, +10000).
The result determines the positive Y damping coefficient, the multiplier of (velocity - minimum velocity) in the positive Y-direction of mouse movement. Also see ChangeViscosity.
Friction
Result is in the range (-10000, +10000).
The result determines the positive Y friction coefficient, the multiplier of (velocity - minimum velocity) in the positive Y-direction of mouse movement.
Grid
Result is in the range (-10000, +10000).
The result determines the strength of the node points in the vertical directions, respectively, when moving down over the grid. Also see ChangeStrength.
Inertia
Result is in the range (-10000, +10000).
The result determines the positive Y inertia coefficient, the multiplier of (acceleration - minimum acceleration) in positive Y-direction of mouse movement.
Spring
Result is in the range (-10000, +10000).
The result determines the positive Y spring constant, the multiplier of (displacement - deadband displacement) from spring center in the positive Y-direction along the spring axis. Also see GetStiffness.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeCoefficientY, GetCoefficientPositiveX, GetCoefficientNegativeX, GetCoefficientNegativeY.


GetDeadBandX

Gets the X deadband of an effect. The meaning of "deadband" is dependent on the type of the effect (see Supported Effects below).

boolean GetDeadBandX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the X deadband of the specified effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Grid
Result is in pixels.
The result specifies the center-to-center horizontal spacing of the grid lines. This sets both the horizontal and vertical spacing to the same value. For a grid, this method is the same as GetSpacingX.
Spring
Result is in pixels.
The result specifies the horizontal distance from the center of the spring over which the effect is not active (no forces are felt).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDeadBand, ChangeDeadBandX, GetDeadBandY


GetDeadBandY

Gets the Y deadband of an effect. The meaning of "deadband" is dependent on the type of the effect (see Supported Effects below).

boolean GetDeadBandY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the Y deadband of the specified effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Grid
Result is in pixels.
The result specifies the center-to-center vertical spacing of the grid lines. This sets both the horizontal and vertical spacing to the same value. For a grid, this method is the same as GetSpacingY.
Spring
Result is in pixels.
The result specifies the vertical distance from the center of the spring over which the effect is not active (no forces are felt).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDeadBand, ChangeDeadBandY, GetDeadBandX


GetDirectionX

Gets the X-direction of an effect, or the X-component of the axis along which the effect operates. The result is the X-component of the direction vector in Cartesian coordinates. The magnitude of the effect cannot be calculated from this direction vector.

long GetDirectionX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the X-direction the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Constant
Specifies the direction of the constant force.
Damper
This method can only be used on a damper effect with a "Directional" axis. See MakeDamper2.
Ellipse
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the ellipse center point. See Remarks below.
Enclosure
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the enclosing rectangle's top left corner. See Remarks below.
Friction
This method can only be used on a friction effect with a "Directional" axis. See MakeFriction2.
Grid
This method can only be used on a grid effect with a "Directional" axis. See MakeGrid2.
Inertia
This method can only be used on an inertia effect with a "Directional" axis. See MakeInertia2.
Periodic
Specifies the axis along which the periodic effect plays.
Ramp
Specifies the direction of the ramp force.
Spring
This method can only be used on a spring with a "Directional" axis. See MakeSpring2.

Remarks

Note that the Cartesian (X, Y-axis) coordinate system in operation here has the Y-axis inverted compared with familiar Cartesian coordinates. On the screen, the positive X-direction is to the right, and the positive Y-direction is down. A vector of (1, 1) points approximately to the bottom right corner of the screen. A vector of (0, -1) points straight up.

Shape effects Ellipse and Enclosure do not behave the same way when rotated. Enclosures are rotated about their top left corners, and Ellipses are rotated about their center points. See the ChangeDirection Tutorial for a pictorial explanation.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDirection, ChangeDirectionPolar, GetDirectionY, GetDirectionPolar


GetDirectionY

Gets the Y-direction of an effect, or the Y-component of the axis along which the effect operates. The result is the Y-component of the direction vector in Cartesian coordinates. The magnitude of the effect cannot be calculated from this direction vector.

long GetDirectionY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the Y-direction the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Constant
Specifies the direction of the constant force.
Damper
This method can only be used on a damper effect with a "Directional" axis. See MakeDamper2.
Ellipse
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the ellipse center point. See Remarks below.
Enclosure
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the enclosing rectangle's top left corner. See Remarks below.
Friction
This method can only be used on a friction effect with a "Directional" axis. See MakeFriction2.
Grid
This method can only be used on a grid effect with a "Directional" axis. See MakeGrid2.
Inertia
This method can only be used on an inertia effect with a "Directional" axis. See MakeInertia2.
Periodic
Specifies the axis along which the periodic effect plays.
Ramp
Specifies the direction of the ramp force.
Spring
This method can only be used on a spring with a "Directional" axis. See MakeSpring2.

Remarks

Note that the Cartesian (X, Y-axis) coordinate system in operation here has the Y-axis inverted compared with familiar Cartesian coordinates. On the screen, the positive X-direction is to the right, and the positive Y-direction is down. A vector of (1, 1) points approximately to the bottom right corner of the screen. A vector of (0, -1) points straight up.

Shape effects Ellipse and Enclosure do not behave the same way when rotated. Enclosures are rotated about their top left corners, and Ellipses are rotated about their center points. See the ChangeDirection Tutorial for a pictorial explanation.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDirection, ChangeDirectionPolar, GetDirectionX, GetDirectionPolar


GetDirectionPolar

Gets the direction of an effect in polar coordinates.

long GetDirectionPolar(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the direction of the specified effect in polar coordinates. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Constant
Specifies the direction of the constant force.
Damper
This method can only be used on a damper effect with a "Directional" axis. See MakeDamper2.
Ellipse
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the ellipse center point. See Remarks below.
Enclosure
Specifies the angle of the left wall of the effect's enclosing rectangle. Effect is rotated about the enclosing rectangle's top left corner. See Remarks below.
Friction
This method can only be used on a friction effect with a "Directional" axis. See MakeFriction2.
Grid
This method can only be used on a grid effect with a "Directional" axis. See MakeGrid2.
Inertia
This method can only be used on an inertia effect with a "Directional" axis. See MakeInertia2.
Periodic
Specifies the axis along which the periodic effect plays.
Ramp
Specifies the direction of the ramp force.
Spring
This method can only be used on a spring with a "Directional" axis. See MakeSpring2.

Remarks

Note that the polar coordinate system in operation here is rotated 180 degrees and inverted compared with familiar polar coordinates. On the screen, an angle of 0 degrees points directly up, an angle of 90 degrees points to the right, an angle of 240 degrees points down and to the left. Angle measurement increases in a clockwise direction.

Shape effects Ellipse and Enclosure do not behave the same way when rotated. Enclosures are rotated about their top left corners, and Ellipses are rotated about their center points. See the ChangeDirection Tutorial for a pictorial explanation.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDirection, ChangeDirectionPolar, GetDirectionX,GetDirectionY


GetDuration

Gets the duration of an effect. The duration of an effect specifies how long the effect persists after being started or triggered.

long GetDuration(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the duration of the specified effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect does not exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeDuration.


GetEffectTypeName

Returns the name of the effect type of the specified effect.

BSTR GetEffectTypeName(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to check.
lResourceReference
The resource reference of this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the name of the effect type of the specified effect. If the effect cannot be found, returns an empty string (""). Possible return values are:

GetEffectType Return Value
"constant"
"damper"
"ellipse"
"enclosure"
"friction"
"grid"
"inertia"
"periodic"
"ramp"
"spring"
"texture"
"compound"

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

Nothing.


GetEnvelopeAttackLevel

Gets the attack level of the envelope (intensity variation with time) of an effect. An envelope has both an attack portion and a fade portion; each of these have an associated level and time. From the beginning of the effect, the force intensity, or level ramps from the attack level to the underlying effect's level over the attack time. At the end of the effect, the magnitude ramps from the effect's level to the fade level over the fade time.

long GetEnvelopeAttackLevel(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the attack level of the envelope. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeEnvelope, GetEnvelopeAttackTime, GetEnvelopeFadeLevel, GetEnvelopeFadeTime.


GetEnvelopeAttackTime

Gets the attack time of the envelope (intensity variation with time) of an effect. An envelope has both an attack portion and a fade portion; each of these have an associated level and time. From the beginning of the effect, the force intensity, or level ramps from the attack level to the underlying effect's level over the attack time. At the end of the effect, the magnitude ramps from the effect's level to the fade level over the fade time.

long GetEnvelopeAttackTime(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the attack time of the envelope in milliseconds. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeEnvelope, GetEnvelopeAttackLevel, GetEnvelopeFadeLevel, GetEnvelopeFadeTime.


GetEnvelopeFadeLevel

Gets the attack level of the envelope (intensity variation with time) of an effect. An envelope has both an attack portion and a fade portion; each of these have an associated level and time. From the beginning of the effect, the force intensity, or level ramps from the attack level to the underlying effect's level over the attack time. At the end of the effect, the magnitude ramps from the effect's level to the fade level over the fade time.

long GetEnvelopeFadeLevel(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the fade level of the envelope. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeEnvelope, GetEnvelopeAttackLevel, GetEnvelopeAttackTime, GetEnvelopeFadeTime.


GetEnvelopeFadeTime

Gets the fade time of the envelope (intensity variation with time) of an effect. An envelope has both an attack portion and a fade portion; each of these have an associated level and time. From the beginning of the effect, the force intensity, or level ramps from the attack level to the underlying effect's level over the attack time. At the end of the effect, the magnitude ramps from the effect's level to the fade level over the fade time.

long GetEnvelopeFadeTime(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the fade time of the envelope in milliseconds. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeEnvelope, GetEnvelopeAttackLevel, GetEnvelopeAttackTime GetEnvelopeFadeLevel.


GetGain

Gets the gain of an effect. The gain is an attenuation level for all forces within the effect - a higher gain value corresponds to less attenuation, and thus a stronger effect.

long GetGain(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the gain of the specified effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeGain.


GetMagnitude

Gets the magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean GetMagnitude(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the magnitude of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
The result is in the range (-10000, +10000).
The result determines the magnitude of the constant force; a negative magnitude exerts a force in the opposite direction.
Periodic
The result is in the range (-10000, +10000).
The result determines the amplitude of the periodic.
Ramp
The result is in the range (-10000, +10000).
The result determines the ramp force at the beginning of the ramp. A negative magnitude exerts a force in the opposite direction.
Texture
The result is in the range (-10000, +10000).
The result determines the magnitude of force exerted at each bump when moving across the texture in the positive X direction. Same as GetMagnitudePositiveX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeX, ChangeMagnitudeY, GetMagnitude2, GetMagnitudePositiveX.


GetMagnitude2

Gets the "second" magnitude of an effect. The meaning of "second magnitude" is dependent on the type of effect (see Supported Effects below).

boolean GetMagnitude2(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the "second" magnitude of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
The result is always 0.
Periodic
The result is always 0.
Ramp
The result is in the range (-10000, +10000).
The result determines the ramp force at the end of the ramp. A negative magnitude exerts a force in the opposite direction.
Texture
The result is in the range (-10000, +10000).
The result determines the magnitude of force exerted at each bump when moving across the texture in the negative X direction. Same as GetMagnitudeNegativeX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeX, ChangeMagnitudeY, GetMagnitude, GetMagnitudeNegativeX.


GetMagnitudeNegativeX

Returns the negative X magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean GetMagnitudeNegativeX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative X magnitude of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result determines the magnitude of force exerted at each bump when moving left over the texture.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeX, GetMagnitudePositiveX, GetMagnitudePositiveY, GetMagnitudeNegativeY.


undefined

Immersion Web Plugin Reference

GetMagnitudeNegativeY

Returns the negative Y magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean GetMagnitudeNegativeY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative Y magnitude of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result determines the magnitude of force exerted at each bump when moving up over the texture.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeX, GetMagnitudePositiveX, GetMagnitudePositiveY, GetMagnitudeNegativeX.


GetMagnitudePositiveX

Returns the positive X magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean GetMagnitudePositiveX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive X magnitude of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result determines the magnitude of force exerted at each bump when moving right over the texture.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeX, GetMagnitudePositiveY, GetMagnitudeNegativeX, GetMagnitudeNegativeY.


GetMagnitudePositiveY

Returns the positive Y magnitude of an effect. The meaning of "magnitude" is dependent on the type of effect (see Supported Effects below).

boolean GetMagnitudePositiveY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive Y magnitude of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result determines the magnitude of force exerted at each bump when moving down over the texture.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMagnitude, ChangeMagnitudeY, GetMagnitudePositiveX, GetMagnitudeNegativeX, GetMagnitudeNegativeY.


GetMinimumX

Returns the X minimum value of an effect. The meaning of "minimum" is dependent on the type of effect (see Supported Effects below).

boolean GetMinimumX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the minimum X value of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (0, +10000).
This result specifies the minimum X velocity necessary to activate the damper effect.
Friction
Result is in the range (0, +10000).
This result specifies the minimum X velocity necessary to activate the friction effect.
Inertia
Result is in the range (0, +10000).
This result specifies the minimum X acceleration necessary to activate the inertia effect.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMinimum, ChangeMinimumX, ChangeMinimumY, GetMinimumY.


GetMinimumY

Returns the Y minimum value of an effect. The meaning of "minimum" is dependent on the type of effect (see Supported Effects below).

boolean GetMinimumY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the Y minimum value of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
Result is in the range (0, +10000).
This result specifies the minimum Y velocity necessary to activate the damper effect.
Friction
Result is in the range (0, +10000).
This result specifies the minimum Y velocity necessary to activate the friction effect.
Inertia
Result is in the range (0, +10000).
This result specifies the minimum Y acceleration necessary to activate the inertia effect.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeMinimum, ChangeMinimumX, ChangeMinimumY, GetMinimumX.


GetNameOfEffectInCompound

Returns the name of an effect in a specified compound effect.

BSTR GetNameOfEffectInCompound(
    BSTR effectName,
    long lResourceReference,
    long lEffectNumber
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The reference number for the resource you wish to query, as returned by OpenForceResource. Pass -1 for the global resource which stores effects created with the "Make" method.
lEffectNumber
The zero-based index of the compound effect whose name you wish to query the name. Valid numbers are between 0 and GetNumberOfEffectsInCompound()-1.

Return Values

Returns the name of the indexed effect in specified compound effect. Returns a NULL string if the effect number is out of range, if the specified effect does not exist, or if the specified effect is not a compound effect.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetNumberOfEffectsInCompound


GetNumberOfEffectsInCompound

Returns the number of effects in the specified compound effect.

long GetNumberOfEffectsInCompound(
    BSTR effectName
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The reference number for the resource you wish to query, as returned by OpenForceResource. Pass -1 for the global resource which stores effects created with the "Make" method.

Return Values

Returns the number of effects in the specified compound effect. Returns -1 if the effect does not exists, if the effect is not a compound effect, or if the resource is not valid.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetNameOfEffectInCompound


GetOffset

Gets the offset of an effect. The meaning of "offset" is dependent on the type of effect (see Supported Effects below).

boolean GetOffset(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the offset of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Grid
Result is in pixels.
The result determines the distance from the left edge of the screen or enclosure at which the first grid effect (node) is felt. The default value of Offset set upon effect initialization is the mouse position on the screen when StartEffect is called. For a grid, this method is the same as GetCenterX.
Periodic
The result is in the range (-10000, +10000).
The result determines the offset to the amplitude of the periodic. This is the magnitude of the force added to all forces exerted during the periodic effect.
Texture
Result in pixels.
The result determines the distance from the left edge of the screen or enclosure at which the first texture effect (bump) is felt.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeOffset, GetOffset2, GetCenterX.


GetOffset

Immersion Web Plugin Reference

GetOffset2

Gets the "second" offset of an effect. The meaning of "second offset" is dependent on the type of effect (see Supported Effects below).

boolean GetOffset2(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the "second" offset of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Grid
Result is in pixels.
The result determines the distance from the top edge of the screen or enclosure at which the first grid effect (node) is felt. The default value of Offset set upon effect initialization is the mouse position on the screen when StartEffect is called. For a grid, this method is the same as GetCenterY.
Periodic
The result is 0.
Texture
Result in pixels.
The result determines the distance from the top edge of the screen or enclosure at which the first texture effect (bump) is felt.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeOffset, GetOffset, GetCenterY.


GetPeriod

Gets the period of a periodic effect. The period is the duration of a single waveform of the periodic, and is the multiplicative inverse of the periodic's frequency (period = 1/frequency).

long GetPeriod(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the period of the specified effect, in milliseconds. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Periodic

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangePeriod.


GetPhase

Gets the phase of a periodic effect. The phase is the (temporal) offset to the period of the periodic. It determines where within the waveform the effect will begin playing.

long GetPhase(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns phase of the specified effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the specified effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Periodic

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangePhase.


GetRectangleLeft

Gets the left position of the bounding rectangle of an effect. This is only applicable to shape effects such as enclosures and ellipses (see Supported Effects below).

long GetRectangleLeft(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the left position of the bounding rectangle of an effect, in pixels. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
Enclosure

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeRectangle, GetRectangleTop, GetRectangleWidth, GetRectangleHeight


GetRectangleTop

Gets the top position of the bounding rectangle of an effect. This is only applicable to shape effects such as enclosures and ellipses (see Supported Effects below).

long GetRectangleTop(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the top position of the bounding rectangle of an effect, in pixels. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
Enclosure

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeRectangle, GetRectangleLeft, GetRectangleWidth, GetRectangleHeight


GetRectangleWidth

Gets the width of the bounding rectangle of an effect. This is only applicable to shape effects such as enclosures and ellipses (see Supported Effects below).

long GetRectangleWidth(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the width of the bounding rectangle of an effect, in pixels. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
Enclosure

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeRectangle, GetRectangleLeft, GetRectangleTop, GetRectangleHeight


GetRectangleHeight

Gets the height of the bounding rectangle of an effect. This is only applicable to shape effects such as enclosures and ellipses (see Supported Effects below).

long GetRectangleHeight(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the height of the bounding rectangle of an effect, in pixels. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
Enclosure

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeRectangle, GetRectangleLeft, GetRectangleTop, GetRectangleWidth


GetSaturation

Get the saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean GetSaturation(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the saturation of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the right across the damper. Returns the same value as GetSaturationPositiveX.
Ellipse
The result is in the range (0, +10000).
The result determines the maximum force felt at the ellipse walls.
Enclosure
The result is in the range (0, +10000).
The result determines the maximum forces felt at the top and bottom enclosure walls.
Friction
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the right across the area exerting friction. Returns the same value as GetSaturationPositiveX.
Grid
The result is in the range (0, +10000).
The result determines the maximum force output felt at the node points of the grid while moving to the right. Returns the same value as GetSaturationPositiveX.
Inertia
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the right across the area exerting inertia. Returns the same value as GetSaturationPositiveX.
Spring
The result is in the range (0, +10000).
The result determines the maximum force output in response to cursor displacement to the right from the spring center. Returns the same value as GetSaturationPositiveX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, GetSaturation2, GetSaturationPositiveX.


GetSaturation2

Get the "second" saturation value of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

long GetSaturation2(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the "second" saturation value of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the left across the damper. Returns the same value as GetSaturationNegativeX.
Ellipse
The result is in the range (0, +10000).
The result determines the maximum force felt at the ellipse walls.
Enclosure
The result is in the range (0, +10000).
The result determines the maximum forces felt at the left and right enclosure walls.
Friction
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the left across the area exerting friction. Returns the same value as GetSaturationNegativeX.
Grid
The result is in the range (0, +10000).
The result determines the maximum force output felt at the node points of the grid while moving to the left. Returns the same value as GetSaturationNegativeX.
Inertia
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the left across the area exerting inertia. Returns the same value as GetSaturationNegativeX.
Spring
The result is in the range (0, +10000).
The result determines the maximum force output in response to cursor displacement to the left from the spring center. Returns the same value as GetSaturationNegativeX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, GetSaturation, GetSaturationNegativeX.


GetSaturationNegativeX

Get the negative X saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean GetSaturationNegativeX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative X saturation of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the left across the damper.
Friction
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the left across the area exerting friction.
Grid
The result is in the range (0, +10000).
The result determines the maximum force output felt at the node points of the grid while moving to the left.
Inertia
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the left across the area exerting inertia.
Spring
The result is in the range (0, +10000).
The result determines the maximum force output in response to cursor displacement to the left from the spring center.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, ChangeSaturationX, ChangeSaturationY, GetSaturationPositiveX, GetSaturationPositiveY, GetSaturationNegativeY.


GetSaturationNegativeY

Get the negative Y saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean GetSaturationNegativeY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative Y saturation of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion upwards across the damper.
Friction
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion upwards across the area exerting friction.
Grid
The result is in the range (0, +10000).
The result determines the maximum force output felt at the node points of the grid while moving upwards.
Inertia
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion upwards across the area exerting inertia.
Spring
The result is in the range (0, +10000).
The result determines the maximum force output in response to cursor displacement upwards from the spring center.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, ChangeSaturationX, ChangeSaturationY, GetSaturationPositiveX, GetSaturationPositiveY, GetSaturationNegativeX.


GetSaturationPositiveX

Get the positive X saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean GetSaturationPositiveX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive X saturation of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the right across the damper.
Friction
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the right across the area exerting friction.
Grid
The result is in the range (0, +10000).
The result determines the maximum force output felt at the node points of the grid while moving to the right.
Inertia
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion to the right across the area exerting inertia.
Spring
The result is in the range (0, +10000).
The result determines the maximum force output in response to cursor displacement to the right from the spring center.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, ChangeSaturationX, ChangeSaturationY, GetSaturationPositiveY, GetSaturationNegativeX, GetSaturationNegativeY.


GetSaturationPositiveY

Get the positive Y saturation of an effect. A saturation is the maximum force applied during the play of an effect, but the specific meaning of "saturation" is dependent on the type of effect (see Supported Effects below).

boolean GetSaturationPositiveY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive Y saturation of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Damper
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion downwards across the damper.
Friction
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion downwards across the area exerting friction.
Grid
The result is in the range (0, +10000).
The result determines the maximum force output felt at the node points of the grid while moving downwards.
Inertia
The result is in the range (0, +10000).
The result determines the maximum force output in response to motion downwards across the area exerting inertia.
Spring
The result is in the range (0, +10000).
The result determines the maximum force output in response to cursor displacement downwards from the spring center.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSaturation, ChangeSaturationX, ChangeSaturationY, GetSaturationPositiveX, GetSaturationNegativeX, GetSaturationNegativeY.


GetSpacingNegativeX

Returns the negative X spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean GetSpacingNegativeX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative X spacing of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
Result is in pixels.
The result specifies the center-to-center spacings of the texture bumps in the negative X direction of travel (to the left).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacing, ChangeSpacingX, ChangeSpacingY, GetSpacingPositiveX, GetSpacingPositiveY, GetSpacingNegativeY.


GetSpacingNegativeY

Returns the negative Y spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean GetSpacingNegativeY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the negative Y spacing of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
Result is in pixels.
The result specifies the center-to-center spacings of the texture bumps in the negative Y direction of travel (upwards).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacing, ChangeSpacingX, ChangeSpacingY, GetSpacingPositiveX, GetSpacingPositiveY, GetSpacingNegativeX.


GetSpacingPositiveX

Returns the positive X spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean GetSpacingPositiveX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive X spacing of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
Result is in pixels.
The result specifies the center-to-center spacings of the texture bumps in the positive X direction of travel (to the right).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacing, ChangeSpacingX, ChangeSpacingY, GetSpacingPositiveY, GetSpacingNegativeX, GetSpacingNegativeY.


GetSpacingPositiveY

Returns the positive Y spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean GetSpacingPositiveY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the positive Y spacing of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
Result is in pixels.
The result specifies the center-to-center spacings of the texture bumps in the positive Y direction of travel (downwards).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacing, ChangeSpacingX, ChangeSpacingY, GetSpacingPositiveX, GetSpacingNegativeX, GetSpacingNegativeY.


GetSpacingX

Gets the X spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean GetSpacingX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the stiffness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Grid
Result is in pixels.
The result specifies the center-to-center spacing of the horizontal grid lines.
Texture
Result is in pixels.
The result specifies the center-to-center spacings of the texture bumps in positive X direction of travel (to the right).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacingX, ChangeSpacingY, GetSpacingY.


GetSpacingY

Gets the Y spacing of an effect. The meaning of "spacing" is dependent on the type of effect (see Supported Effects below).

boolean GetSpacingY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the stiffness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Grid
Result is in pixels.
The result specifies the center-to-center spacing of the vertical grid lines.
Texture
Result is in pixels.
The result specifies the center-to-center spacings of the texture bumps in negative X direction of travel (to the left).

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeSpacingX, ChangeSpacingY, GetSpacingX.


GetStartDelay

Gets the start delay of an effect. The start delay of an effect specifies the amount of time to delay the playing of an effect after it is started with StartEffect.

long GetStartDelay(
    BSTR effectName,
    long lResourceReference,
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the start delay of the specified effect, in milliseconds. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Constant
Damper
Ellipse
Enclosure
Friction
Grid
Inertia
Periodic
Ramp
Spring
Texture

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeStartDelay.


GetStiffness

Gets the stiffness of an effect. The meaning of "stiffness" is dependent on the type of the effect (see Supported Effects below).

boolean GetStiffness(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the stiffness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
The result is in the range (-10000, +10000).
The result specifies the stiffness of all the ellipse walls. Negative and positive values of stiffness cause a variety of different behaviors when combined with different stiffness mask values (see ChangeStiffnessMask).
Enclosure
The result is in the range (-10000, +10000).
The result specifies the stiffness of the top and bottom enclosure walls. Negative and positive values of stiffness cause a variety of different behaviors when combined with different stiffness mask values (see ChangeStiffnessMask).
Spring
The result is in the range (-10000, +10000).
The result specifies a single value of the spring coefficient for both the positive and negative directions of cursor displacement from the spring center.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeStiffnessMask, GetStiffness2, GetStiffnessMask.


GetStiffness2

Gets the "second" stiffness of an effect. The meaning of "stiffness" is dependent on the type of the effect (see Supported Effects below).

boolean GetStiffness2(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the "second" stiffness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
The result is in the range (-10000, +10000).
The result specifies the stiffness of all the ellipse walls. Negative and positive values of stiffness cause a variety of different behaviors when combined with different stiffness mask values (see ChangeStiffnessMask). This is the same result as GetStiffness.
Enclosure
The result is in the range (-10000, +10000).
The result specifies the stiffness of the left and right enclosure walls. Negative and positive values of stiffness cause a variety of different behaviors when combined with different stiffness mask values (see ChangeStiffnessMask).
Spring
The result is in the range (-10000, +10000).
The result specifies a single value of the spring coefficient for both the positive X direction of cursor displacement from the spring center. This is the same result as GetStiffness, which is that same as GetCoefficientPostiveX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeCoefficient, ChangeStiffnessMask, GetStiffness, GetStiffnessMask.


GetStiffnessMask

Gets the stiffness mask of an effect. A stiffness mask specifies which walls of a shape are active (exerting forces). This method applies only to enclosures and ellipses (see Supported Effects below).

long GetStiffnessMask(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to change.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the stiffness mask of the specified effect. If you attempt to change the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
The result is a mask created by OR-ing the flags below.
Ellipse Clipping Masks
Flag

Any inner wall

0x66

Any outer wall

0x99

Any wall

0xFF

Enclosure
The result is a mask created by OR-ing the flags below.
Enclosure Clipping Masks
Flag

None

0x00

Outer left wall

0x01

Inner left wall

0x02

Inner right wall

0x04

Outer right wall

0x08

Outer top wall

0x10

Inner top wall

0x20

Inner bottom wall

0x40

Outer bottom wall

0x80

Inner any wall

0x66

Outer any wall

0x99

Any wall

0xFF

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeStiffnessMask.


GetThickness

Gets the thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean GetThickness(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Gets the thickness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
The result is in pixels.
The result specifies the width of all the ellipse walls.
Enclosure
The result is in pixels
The result specifies the width of the top and bottom enclosure walls.
Texture
The result is in the range (-10000, +10000).
The result specifies the widths of the texture's bumps in the positive-X direction of motion (to the right). For a texture, this is the same result as GetCoefficientPositiveX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, GetThickness2.


GetThickness

Immersion Web Plugin Reference

GetThickness2

Gets the "second" thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean GetThickness2(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Gets the "second" thickness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Ellipse
The result is in pixels.
The result specifies the width of all the ellipse walls. This is same result as GetThickness.
Enclosure
The result is in pixels
The result specifies the width of the left and right enclosure walls.
Texture
The result is in the range (-10000, +10000).
The result specifies the widths of the texture's bumps in the negative-X direction of motion (to the left). For a texture, this is the same result as GetCoefficientNegativeX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, GetThickness.


GetThicknessNegativeX

Gets the negative-X thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean GetThicknessNegativeX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Gets the negative-X thickness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result specifies the width of the texture's bumps in the negative-X direction of motion (to the left). For a texture, this is the same result as GetCoefficientNegativeX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, GetThickness2, GetThicknessPositiveX, GetThicknessPositiveY, GetThicknessNegativeY.


GetThicknessNegativeY

Gets the negative-Y thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean GetThicknessNegativeY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Gets the negative-Y thickness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result specifies the width of the texture's bumps in the negative-Y direction of motion (upwards). For a texture, this is the same result as GetCoefficientNegativeY.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, GetThickness2, GetThicknessPositiveX, GetThicknessPositiveY, GetThicknessNegativeX.


GetThicknessPositiveX

Gets the positive-X thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean GetThicknessPositiveX(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Gets the positive-X thickness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result specifies the width of the texture's bumps in the positive-X direction of motion (to the right). For a texture, this is the same result as GetCoefficientPositiveX.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, GetThickness2, GetThicknessPositiveY, GetThicknessNegativeX, GetThicknessNegativeY.


GetThicknessPositiveY

Gets the positive-Y thickness of an effect. The meaning of "thickness" is dependent on the type of effect (see Supported Effects below).

boolean GetThicknessPositiveY(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Gets the positive-Y thickness of the specified effect. If you attempt to get the property of an effect that doesn't support the property (see Supported Effects below) or if the effect doesn't exist, 0xDEAD will be returned.

Supported Effects

Texture
The result is in the range (-10000, +10000).
The result specifies the width of the texture's bumps in the positive-Y direction of motion (downwards). For a texture, this is the same result as GetCoefficientPositiveY.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

ChangeThickness, GetThickness2, GetThicknessPositiveX, GetThicknessNegativeX, GetThicknessNegativeY.


GetWaveform

Returns the waveform type of an effect.

long GetWaveform(
    BSTR effectName,
    long lResourceReference
);

Parameters

effectName
The name of the effect to get from.
lResourceReference
The resource reference for this effect, as returned by OpenForceResource. Pass -1 for effects created with a "Make" method.

Return Values

Returns the waveform type of an effect. Possible return values are:

Name | Value | Meaning
wfSine | 0 | Sine wave
wfSquare | 1 | Square wave
wfTriangle | 2 | Triangle wave
wfSawtoothUp | 3 | Sawtooth Up wave
wfSawtoothDown | 4 | Sawtooth Down wave

Supported Effects

Periodic

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

MakePeriodic, MakePeriodic2.


Make Effect Methods

Effects are created in one of two ways: through hard coding or using Immersion Studio and saving to an IFR file. To create an effect by hard coding, you will call one of the "Make" method listed below. Most types of possible effects are supported by the Immersion Web Plugin. Immersion Studio is a program that allows you to create effects without having to use JavaScript. This program creates an IFR file which the Immersion Web Plugin can load using OpenForceResource.

All effects are referred to by a name, such as "Tremor". When using a Make method, you assign a name to an effect you create. To load an effect from an IFR file, you must already know the name of the effect. [Immersion has created a library of effects to give developers an idea of what is possible.]

All effects are associated with a resource (known as a "Project" in Immersion Studio). When you load an IFR file, OpenForceResource returns a resource reference. This reference must be used when trying to Change an effect. When an effect is created with a "Make" method, that effect is associated with the global resource reference, -1.

Compound effects can be loaded using OpenForceResource. However, dynamically making and changing compound effects is not yet supported by the Plugin.

The default parameters for all effects made with a "Make" method are the same as the IFC defaults. Consult the IFC Reference for these values.

Make Effect Methods
MakeConstant | MakeInertia
MakeDamper | MakeInertia2
MakeDamper2 | MakePeriodic
MakeEllipse | MakePeriodic2
MakeEnclosure | MakeRamp
MakeFriction | MakeSpring
MakeFriction2 | MakeSpring2
MakeGrid | MakeTexture
MakeGrid2 | OpenForceResource


MakeConstant

Dynamically creates a constant force effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeConstant(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


MakeDamper

Dynamically creates a damper effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeDamper(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

This damper has a default axis setting of axBothAxes, meaning that it operates in both the X and Y axes. To choose another axis setting, use MakeDamper2.

The default value of the damper's center is the mouse position on the screen when StartEffect is called. If a uniform damper effect is desired, this default value must be changed with ChangeCenter before the effect is started.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

MakeDamper2


MakeDamper2

Dynamically creates a damper effect, with additional parameters that specify the axis of the effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeDamper2(
    BSTR effectName,
    long lAxis
);

Parameters

effectName
The name of the new effect.
lAxis
Specifies which axes of the damper are active. Choose from the following values:
Name | Value | Meaning
axDirectional | 0 | Directional
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

ChangeDirection and ChangeDirectionPolar can only only be used on effects created with the axDirectional setting.

Effects created with axDirectional, axXAxis, or axYAxis operate only along one axis. Effects created with axBothAxes operate in both the X- and Y- directions

Once a damper effect is created, its axis cannot be changed.

The default value of the damper effect's center is the mouse position on the screen when StartEffect is called. If a uniform damper effect is desired, this default value must be changed with ChangeCenter before the effect is started.

Plugin Version Compatibility

Version 3.2.0.4: Passing an undefined value as lAxis results in axBothAxes being used instead.

Version 3.2.2.0: Passing an invalid value for lAxis will return FALSE and the effect will not be created.

See Also

MakeDamper


MakeEllipse

Dynamically creates an ellipse effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeEllipse(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

The default value of the ellipse's center is the mouse position on the screen when StartEffect is called. After it is created, the center can be changed by calling ChangeCenter.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


MakeEnclosure

Dynamically creates an enclosure effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeEnclosure(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

The default value of the enclosure's center is the mouse position on the screen when StartEffect is called. After it is created, the center can be changed by calling ChangeCenter.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


MakeFriction

Dynamically creates a friction effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeFriction(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

This friction has a default axis setting of axBothAxes, meaning that it operates in both the X and Y axes. To choose another axis setting, use MakeFriction2.

The default value of the friction effect's center is the mouse position on the screen when StartEffect is called. If a uniform friction effect is desired, this default value must be changed with ChangeCenter before the effect is started.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

MakeFriction2


MakeFriction2

Dynamically creates a friction effect, with additional parameters that specify the axis of the effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeFriction2(
    BSTR effectName,
    long lAxis
);

Parameters

effectName
The name of the new effect.
lAxis
Specifies which axes of the friction effect are active. Choose from the following values:
Name | Value | Meaning
axDirectional | 0 | Directional
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

ChangeDirection and ChangeDirectionPolar can only only be used on effects created with the axDirectional setting.

Effects created with axDirectional, axXAxis, or axYAxis operate only along one axis. Effects created with axBothAxes operate in both the X- and Y- directions.

Once a friction effect is created, its axis cannot be changed.

The default value of the friction effect's center is the mouse position on the screen when StartEffect is called. If a uniform friction effect is desired, this default value must be changed with ChangeCenter before the effect is started.

Plugin Version Compatibility

Version 3.2.0.4: Passing an undefined value as lAxis results in axBothAxes being used instead.

Version 3.2.2.0: Passing an invalid value for lAxis will return FALSE and the effect will not be created.

See Also

MakeFriction


MakeGrid

Dynamically creates a grid effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeGrid(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

The default value of the grid's center is the mouse position on the screen when StartEffect is called. After it is created, the center can be changed by calling ChangeCenter or ChangeOffset.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

MakeGrid2.


MakeGrid2

Dynamically creates a grid effect, with additional parameters that specify the axis of the effect. This effect is stored in a special resource project which has a resource reference of -1..

boolean MakeGrid2(
    BSTR effectName,
    long lAxis
);

Parameters

effectName
The name of the new effect.
lAxis
Specifies which axes of the friction effect are active. Choose from the following values:
Name | Value | Meaning
axDirectional | 0 | Directional
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

ChangeDirection and ChangeDirectionPolar can only only be used on effects created with the axDirectional setting.

Effects created with axDirectional, axXAxis, or axYAxis operate only along one axis. Effects created with axBothAxes operate in both the X- and Y- directions.

Passing an undefined value as lAxis results in axBothAxes being used instead.

Once a grid effect is created, its axis cannot be changed.

The default value of the grid's center is the mouse position on the screen when StartEffect is called. After it is created, the center can be changed by calling ChangeCenter or ChangeOffset.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

MakeGrid.


MakeInertia

Dynamically creates an inertia effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeInertia(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

This inertia has a default axis setting of axBothAxes, meaning that it operates in both the X and Y axes. To choose another axis setting, use MakeInertia2.

The default value of the inertia effect's center is the mouse position on the screen when StartEffect is called. If a uniform inertia effect is desired, this default value must be changed with ChangeCenter before the effect is started.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

MakeInertia2


MakeInertia2

Dynamically creates a inertia effect, with additional parameters that specify the axis of the effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeInertia2(
    BSTR effectName,
    long lAxis
);

Parameters

effectName
The name of the new effect.
lAxis
Specifies which axes of the inertia effect are active. Choose from the following values:
Name | Value | Meaning
axDirectional | 0 | Directional
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

ChangeDirection and ChangeDirectionPolar can only only be used on effects created with the axDirectional setting.

Effects created with axDirectional, axXAxis, or axYAxis operate only along one axis. Effects created with axBothAxes operate in both the X- and Y- directions.

Once an inertia effect is created, its axis cannot be changed.

The default value of an inertia effect's center is the mouse position on the screen when StartEffect is called. If a uniform inertia effect is desired, this default value must be changed with ChangeCenter before the effect is started.

Plugin Version Compatibility

Version 3.2.0.4: Passing an undefined value as lAxis results in axBothAxes being used instead.

Version 3.2.2.0: Passing an invalid value for lAxis will return FALSE and the effect will not be created.

See Also

MakeInertia


MakePeriodic

Dynamically creates periodic effect with a sine waveform. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakePeriodic(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

The created periodic has a default waveform setting of wfSineWave. To create a periodic with another waveform, use MakePeriodic2.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

MakePeriodic2.


MakePeriodic2

Dynamically creates a periodic effect with a specified waveform. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakePeriodic2(
    BSTR effectName,
    long lWaveform
);

Parameters

effectName
The name of the new effect.
lWaveform
The type of waveform to create. Choose from the following values:
Name | Value | Meaning
wfSine | 0 | Sine wave
wfSquare | 1 | Square wave
wfTriangle | 2 | Triangle wave
wfSawtoothUp | 3 | Sawtooth Up wave
wfSawtoothDown | 4 | Sawtooth Down wave

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

Passing an undefined value as lWaveform results in wfSine being used instead.

Once a periodic is created, its waveform cannot be changed.

Plugin Version Compatibility

Requires version 3.2.1.0 or greater.

See Also

MakePeriodic.


MakeRamp

Dynamically creates a ramp effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeRamp(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


MakeSpring

Dynamically creates a spring effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeSpring(
    BSTR effectName
);

Parameters

effectName
The name of the new effect.

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

This spring has a default axis setting of axBothAxes, meaning that it operates in both the X and Y axes. To choose another axis setting, use MakeSpring2.

The default value of the spring's center is the mouse position on the screen when StartEffect is called. After it is created, the center can be changed by calling ChangeCenter.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

MakeSpring2


MakeSpring2

Dynamically creates a spring effect, with additional parameters that specify the axis of the effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeSpring2(
    BSTR effectName,
    long lAxis
);

Parameters

effectName
The name of the new effect.
lAxis
Specifies which axes of the spring effect are active. Choose from the following values:
Name | Value | Meaning
axDirectional | 0 | Directional
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

ChangeDirection and ChangeDirectionPolar can only only be used on effects created with the axDirectional setting.

Effects created with axDirectional, axXAxis, or axYAxis operate only along one axis. Effects created with axBothAxes operate in both the X- and Y- directions.

Once a spring effect is created, its axis cannot be changed.

The default value of the spring's center is the mouse position on the screen when StartEffect is called. After it is created, the center can be changed by calling ChangeCenter.

Plugin Version Compatibility

Version 3.2.0.4: Passing an undefined value as lAxis results in axBothAxes being used instead.

Version 3.2.2.0: Passing an invalid value for lAxis will return FALSE and the effect will not be created.

See Also

MakeSpring


MakeTexture

Dynamically creates a texture effect. This effect is stored in a special resource project which has a resource reference of -1.

boolean MakeTexture(
    BSTR effectName,
    long lAxis
);

Parameters

effectName
The name of the new effect.
lAxis
Specifies which axes of the texture effect are active. Choose from the following values:
Name | Value | Meaning
axXAxis | 1 | X (Horizontal) Axis
axYAxis | 2 | Y (Vertical) Axis
axBothAxes | 3 | Both X and Y Axes

Return Values

Returns TRUE if successful, FALSE otherwise.

Remarks

Textures created with axXAxis or axYAxis operate only along one axis. Effects created with axBothAxes operate in both the X- and Y- directions.

Passing an undefined value as lAxis results in axBothAxes being used instead.

Once a texture is created, its axis cannot be changed.

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Nothing.


Version Information Methods

The following "Version Information" methods allow developers to query the versions of the various TouchSense software components on a user's system.

Version Information Methods
GetDriverVersion
GetDXVersion
GetIDesktopVersion
GetIFCVersion
GetImmAPIVersion
GetPluginVersion
ImmWebInstalled


GetDriverVersion

Returns the version string of the driver software used by the currently acquired device.

BSTR GetDriverVersion();

Parameters

None.

Return Values

Returns the version string of the driver software used by the currently acquired device. The version string is in the form "Major#.Minor#.BuildMajor#.BuildMinor#".

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetPluginVersion, GetIFCVersion, GetImmAPIVersion, GetDXVersion, GetIDesktopVersion.


GetDXVersion

Returns the version string of the DirectInput library installed on the user's machine.

BSTR GetDXVersion();

Parameters

None.

Return Values

Returns the version string of the DirectInput library installed on the user's machine. The version string is in the form "Major#.Minor#.BuildMajor#.BuildMinor#".

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetPluginVersion, GetIFCVersion, GetImmAPIVersion, GetDriverVersion , GetIDesktopVersion.


GetIDesktopVersion

Returns the version string of the Immersion Desktop application that the user has installed on their system.

BSTR GetIDesktopVersion();

Parameters

None.

Return Values

Returns the version string of the Immersion Desktop application that the user has installed on their system. The version string is in the form "Major#.Minor#.BuildMajor#.BuildMinor#".

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetPluginVersion, GetImmAPIVersion, GetIFCVersion, GetDXVersion, GetDriverVersion .


GetIFCVersion

Returns the version string of the Immersion Foundation Classes (IFC) library that the Immersion Web Plugin is using.

BSTR GetIFCVersion();

Parameters

None.

Return Values

Returns the version string of the Immersion Foundation Classes (IFC) library that the Immersion Web Plugin is using. The version string is in the form "Major#.Minor#.BuildMajor#.BuildMinor#".

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetPluginVersion, GetImmAPIVersion, GetDXVersion, GetDriverVersion , GetIDesktopVersion.


GetImmAPIVersion

Returns the version string of the Immersion API libary used by the currently acquired device.

BSTR GetImmAPIVersion();

Parameters

None.

Return Values

Returns the version string of the Immersion API library used by the currently acquired device. The version string is in the form "Major#.Minor#.BuildMajor#.BuildMinor#".

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetPluginVersion,GetIFCVersion, GetDXVersion, GetDriverVersion , GetIDesktopVersion.


GetPluginVersion

Returns the version string of the Immersion Web Plugin.

BSTR GetPluginVersion();

Parameters

None.

Return Values

Returns the version string of the Immersion Web Plugin. The version string is in the form "Major#.Minor#.BuildMajor#.BuildMinor#".

Remarks

None.

Plugin Version Compatibility

Requires version 3.2.2.0 or greater.

See Also

GetIFCVersion, GetImmAPIVersion, GetDXVersion, GetDriverVersion , GetIDesktopVersion.


ImmWebInstalled

Returns TRUE if the Immersion Web Plugin is installed. This method is only meant to be used in JavaScript. See the Remarks section below.

boolean ImmWebInstalled();

Parameters

None.

Return Values

When method name only (without "()") is called from JavaScript within Microsoft Internet Explorer, returns TRUE if the Immersion Web Plugin is installed. Otherwise, returns FALSE.

Remarks

Use this method in JavaScript within Internet Explorer to determine whether the Immersion Web Plugin is installed.

In JavaScript in Internet Explorer, a call to the name only of a parameterless method of an object that does not exist will return FALSE. Here is a code snippet which illustrates using this method to detect the presence of the plugin in Internet Explorer:

 <OBJECT
classid="CLSID:5CA42785-ABC3-11d2-9F81-00104B2225C5"
id="ImmWeb"
codebase="#version=3,2,2,1"
height="0" width="0">
<EMBED type="application/x-Immersion-Web-Plugin"
name="ImmWeb" hidden="true"
  src="myfile.txt">
</OBJECT>

<SCRIPT>
if(!document.ImmWeb.ImmWebInstalled) {
alert( 'The Immersion
  Web Plugin is not installed!' );
}
</SCRIPT>

Plugin Version Compatibility

Requires version 3.2.0.4 or greater.

See Also

Immersion Web Plugin Detection and Download