IBM PS/2 8516 Touch Display Device Driver Support: Difference between revisions

From OS2World.Com Wiki
Jump to navigation Jump to search
Line 3,808: Line 3,808:
===CLICK LOCKING===
===CLICK LOCKING===


Click locking is the process by which the touch
Click locking is the process by which the touch (x,y) coordinate gets locked onto a value before being sent to the system as emulated mouse data.
(x,y) coordinate gets locked onto a value before
being sent to the system as emulated mouse data.


Note: Click locking only affects touch data when
Note: Click locking only affects touch data when it is sent as emulated mouse data and does not interfere with the normal use of an IBM PS/2 mouse if one is attached to the IBM PS/2 Touch Display 8515, or the data sent in full touch pointing mode.
      it is sent as emulated mouse data and does
      not interfere with the normal use of an IBM
      PS/2 mouse if one is attached to the IBM
      PS/2 Touch Display 8515, or the data sent
      in full touch pointing mode.


Click locking is performed because some actions
Click locking is performed because some actions which are done with the mouse button being clicked require that little movement of the mouse pointer itself should take place.  Click locking makes the action of double clicking using the touch display easier as it removes the need to maintain the touch position at exactly the same point between clicks.
which are done with the mouse button being clicked
require that little movement of the mouse pointer
itself should take place.  Click locking makes the
action of double clicking using the touch display
easier as it removes the need to maintain the
touch position at exactly the same point between
clicks.


Prime examples of this can be found in OS/2
Prime examples of this can be found in OS/2 Presentation Manager:
Presentation Manager:


Clicking on an icon to bring up the system
* Clicking on an icon to bring up the system menu, or double clicking to activate the window.
    menu, or double clicking to activate the
    window.


    The first of these actions, when attempted
: The first of these actions, when attempted with the touch display emulating the mouse can occasionally result in the icon simply moving a few pixels, as the PM shell will misinterpret the 'click down with associated movement' as a drag operation to move the icon. This is because it decides that if the movement is more than a few pixels it must be click with drag rather than a simple click.
    with the touch display emulating the mouse can
    occasionally result in the icon simply moving
    a few pixels, as the PM shell will
    misinterpret the 'click down with associated
    movement' as a drag operation to move the
    icon. This is because it decides that if the
    movement is more than a few pixels it must be
    click with drag rather than a simple click.


    Thus even a single click action is sometimes
: Thus even a single click action is sometimes unsuccessful.  Even less successful will be the double click action: even if the first click can be done without causing the icon to move, the second click must be done at the same position (actually PM allows a small movement of 6 pixels in the x direction and 8 pixels in the y direction). With a great deal of practice, this condition can be met, but perhaps with only a 20% success rate (tip: for least x,y movement the force variation should be kept to a minimum. In other words, don not press harder than necessary to achieve the button down threshold, and do not lift off completely between clicks, rather just release sufficiently to go below the button up threshold).  The normal outcome of such an attempted action is that the icon will move and/or the system menu will appear.
    unsuccessful.  Even less successful will be
    the double click action: even if the first
    click can be done without causing the icon to
    move, the second click must be done at the
    same position (actually PM allows a small
    movement of 6 pixels in the x direction and 8
    pixels in the y direction). With a great deal
    of practice, this condition can be met, but
    perhaps with only a 20% success rate (tip: for
    least x,y movement the force variation should
    be kept to a minimum. In other words, don not
    press harder than necessary to achieve the
    button down threshold, and do not lift off
    completely between clicks, rather just release
    sufficiently to go below the button up
    threshold).  The normal outcome of such an
    attempted action is that the icon will move
    and/or the system menu will appear.


    It is this difficulty, of maintaining the x,y
: It is this difficulty, of maintaining the x,y position while button clicking, that click locking attempts to remedy. While being mainly applicable to PM, the technique is also useful in the DOS 4.0 shell, or indeed any application (usually in graphics mode) that uses the mouse.
    position while button clicking, that click
    locking attempts to remedy. While being
    mainly applicable to PM, the technique is also
    useful in the DOS 4.0 shell, or indeed any
    application (usually in graphics mode) that
    uses the mouse.


The three click locking options that may be chosen are:
The three click locking options that may be chosen are:
    No click locking
: No click locking
    Single click locking
: Single click locking
    Double click locking
: Double click locking


NO CLICK LOCKING
NO CLICK LOCKING
Line 3,893: Line 3,844:
DOUBLE CLICK LOCKING
DOUBLE CLICK LOCKING


This option is the same as single click locking, except that the conditions for normal reporting of
This option is the same as single click locking, except that the conditions for normal reporting of (x,y) data are:
(x,y) data are:
* After the click lock time has been exceeded.
* After the click lock time has been exceeded.
* If the touch coordinate moves outside the click lock area
* If the touch coordinate moves outside the click lock area
Line 3,902: Line 3,852:
CLICK LOCK AREA
CLICK LOCK AREA


This value determines the size of one side of a
This value determines the size of one side of a square which defines the click lock area. The centre of the square is located at the (x,y) position at which the coordinates become locked.
square which defines the click lock area. The
When the touch coordinate moves outside the click lock area, normal (x,y) reporting is resumed.
centre of the square is located at the (x,y)
position at which the coordinates become locked.
When the touch coordinate moves outside the click
lock area, normal (x,y) reporting is resumed.


The value is in pixel units, and will therefore
The value is in pixel units, and will therefore vary with screen resolution if a click lock area of a given physical dimension is required.
vary with screen resolution if a click lock area
of a given physical dimension is required.


A large value will make double clicking at a point
A large value will make double clicking at a point very easy, but at the expense of making immediate minor adjustment/close manipulation by dragging slightly more cumbersome.
very easy, but at the expense of making immediate
minor adjustment/close manipulation by dragging
slightly more cumbersome.


CLICK LOCK TIME
CLICK LOCK TIME


This value determines the time which is allowed to
This value determines the time which is allowed to elapse from the time the coordinates first become locked to when normal (x,y) reporting is resumed.
elapse from the time the coordinates first become
locked to when normal (x,y) reporting is resumed.


A large value will make double clicking a more
A large value will make double clicking a more unhurried process, but at the expense of making immediate minor adjustment/close manipulation by dragging slightly more cumbersome.
unhurried process, but at the expense of making
immediate minor adjustment/close manipulation by
dragging slightly more cumbersome.


PSEUDOCODE
PSEUDOCODE
Line 3,948: Line 3,884:
                     sd_count = 0
                     sd_count = 0
</PRE>
</PRE>
On entry to the procedure the x,y values are set to the current
On entry to the procedure the x,y values are set to the current x,y coordinate report. A bit in a status word (selection detection bit) reflects the binary state of the emulated mouse
x,y coordinate report. A bit in a status word (selection
detection bit) reflects the binary state of the emulated mouse
button (1= button down 0= button up).
button (1= button down 0= button up).
<PRE>
<PRE>

Revision as of 23:00, 4 January 2024

Article Info
Author IBM
Date 7th September 1992
OS Version IBM OS/2 2.0
Companion File
Source [1]

Abstract

The IBM PS/2 8516 Touch Display Driver Support document attached contains information on OS/2 version 2.0 Device Independent API function calls and all IOCtl commands. For information on DOS and OS/2 1.2/1.3 API calls please see the 8516 Technical Reference (P/N 92F2673).

Device driver overview

This add-on component to OS/2 2.0 provides support for the IBM PS/2 8516 Touch Display pointing device. IBM PS/2 8516 Touch Display is essentially a PS/2 8515 Display, which, besides the normal video cable connection to a VGA/XGA port, has a touch data cable which attaches to the IBM PS/2 Mouse (pointing device) port on the system unit. In addition, the monitor itself has a socket to which the IBM PS/2 Mouse may optionally be attached.

Support for IBM PS/2 8516 Touch Display for OS/2 (protected) mode and DOS (real) mode applications will be provided by six components:

  • A touch device independent subsystem
  • A touch device driver
  • A touch device dependent subsystem
  • A combined IBM PS/2 Mouse/touch device dependent device driver
  • A touch virtual device driver
  • An ABIOS RAM extension for both IBM PS/2 Mouse and IBM PS/2 8516 Touch Display devices (Not required for Family 1 machines).

Note:

Support for IBM PS/2 8516 Touch Display as a video device is provided by standard 8515 device drivers: indeed, as far as the system is concerned, there is no difference video-wise between this monitor and a standard 8515.

The differences between this support and previous OS/2 1.2/3 support are:

  • Revised touch API which is device independent.
Programs written to the existing TouXXX API using device dependent features (thresholds, filter type etc.) will, however, remain compatible (by virtualising some functions, others will become no-ops).
  • Device dependent features (only) accessed by PM control panel or device driver load time parameters (using common TOUCH.INI file).
  • PM mouse emulation support for windowed DOS sessions.
  • VDD gives DOS touch API (INT 7Fh) support for multiple full screen DOS sessions.
A DOS property is also available which provides 'exclusive touch access' for a windowed DOS session. This disables mouse emulation and gives the DOS application direct full screen x,y,z touch coordinates. If the DOS session is not maximised to cover the full screen then coordinate mapping by the application would be required.

Figure 1 shows the arrangement of the touch and mouse device drivers.

                      Presentation Manager
   MouXXX  A            A      A                                      A  TdiXXX              A TouXXX
   API     |            |      |                                      |  API                 | API
  *--------V--------*   |      |                             *--------V--------*    *--------V--------*
  |   MOUCALLS.DLL  |   |      |                             |   TDICALLS.DLL  <---->   TOUCALLS.DLL  |
  *--------A--------*   |      |                             *--------A--------*    *-----------------*
           |            |      |                                      |
  *--------V--------*   |      |   INT33 DOS             INT7F DOS    *---------*
  |   BMSCALLS.DLL  |   |      |      A  API                 A API              |
  *--------A--------*   |      |      |                      |                  | DosDevIOCtl
DosDevIOCtl|   *--------*      |      |                      |                  |
  *--------V---V----*    *-----V------V----*    *------------V----*    *--------V--------*
  |                 |    |                 |    |                 |    |                 |
  | MOUSE.SYS       |-->-| VMOUSE.SYS      |    | VTOUCH.SYS      |-<--| TOUCH.SYS       |
  |                 |--<-|                 |    |                 |->--|                 |
  |                 |    |                 |    |                 |    |                 |
  |                 |    |                 |    |                 |    |                 |
  *-----------------*    *-----------------*    *-----------------*    *-----------------*
       |       *-------------------<--------*                                  |
       *-----------<------* Emulated mouse  | *------->------------------------*
             Mouse data   A      data       A A   Touch data
                  *-------+-----------------+-+--------*
                  |       |        |     *-------*     |                           (device
 PDITOU02.SYS     |       *------* | *---|   E   |     |      *-----------------*   dependent)
 Combined mouse   |           *---------**-------*     <------>   TDDCALLS.DLL  <---->  TDDxxx
 touch device     |           |    I    |              |      *-----------------*       API
 dependent driver | PDIMOU$   *---------*   PDITOU$    |
                  *----------------+-------------------*
                                   A
                           *-----------------*
              TOUMOUSx.BIO |     ABIOS       |
                           *-----------------*
                                   A
                                   |
                       Mouse/touch display hardware

Figure 1. Schematic diagram of touch/mouse device drivers and subsystems

Notes:

  1. The box marked I is the interrupt handler which decides whether the data packet is mouse or touch data.
  2. The box marked E is controlled by the state of mouse emulation. Data is either passed to the mouse or touch device driver depending on whether mouse emulation is on or off respectively.

Note how both the IBM PS/2 Mouse and IBM PS/2 8516 Touch Display devices share the same ABIOS and device dependent driver. These components are not separable due to the access of the devices through the same physical I/O ports on the 8042, and sharing the same physical hardware interrupt request IRQ12h. This implies a common device driver with a single interrupt handler, which decides by examination of the actual data itself, which device was responsible for the interrupt.

Note also that the physical arrangement of the mouse drivers, where only one device dependent driver may attach to the device independent driver, which means that if a mouse other than the IBM PS/2 Mouse is used in conjunction with IBM PS/2 8516 Touch Display (for example the Microsoft Mouse attached to the serial port), either the serial mouse device dependent driver can attach to mouse.sys, or the combined driver can attach to mouse.sys (this being controlled by the device name specified in the TYPE= keyword of the DEVICE=MOUSE.SYS config.sys entry).

In the former case, the mouse emulation facility is not available, however the combined driver, can still attach to just the touch device independent driver, such that the two devices, mouse and touch, are completely separate, with the touch device only available to applications written to the touch API's.

In the latter case, the physical mouse would not be operable, though the touch device mouse emulation facility would function.

The use of a mouse other than the IBM PS/2 Mouse therefore, does not preclude the use of the touch screen when used with specifically written touch applications, though it does mean that mouse emulation by the touch screen, for example to drive Presentation Manager using touch, is not available (unless the physical mouse is disabled).

APIs

To access the touch display device, DOS mode applications use the software interrupt 7FH (INT7FH) interface described under "DOS Device Dependent API," while OS/2 mode applications use the Tdixxx API described under "OS/2 Device Independent Subsystem and API." OS/2 mode applications may not use the INT7FH API nor may DOS mode applications use the Tdixxx API.

The TouXXX API provided in OS/2 1.2/3 is also available, but due to the fact that all of the hardware dependent functions have been moved out of the TOUCH.SYS driver into the PDITOU0x.SYS driver, thus making the TOUCH.SYS driver truly 'device independent'

Besides the touch device capability, it is also possible to use the touch display to emulate the IBM PS/2 Mouse. In this case the standard mouse INT33H API (for DOS mode) and MOUxxx API (for OS/2 mode) are used.

32-Bit Programming

The API's described above are 16bit API's, there are is no 32bit API available for the touch device. Programs compiled for the 32 bit flat model (CL386 -G3 switch) may still use the 16 bit API calls using the CL386 compiler's built in 16->32 bit conversions. These are brought into play when pointer parameters and function calls are declared with the "_far16" keyword. The complier then generates the necessary 'thunking' code to perform the call.

For further information see the OS/2 2.0 Toolkit documentation, Appendix headed "Mixed Model Programming", section headed "Calling from 32-bit code to 16-bit API's".

Presentation Manager

Within Presentation Manager it is not possible to access the touch device as such from a:

  1. Presentation Manager program
  2. AVIO window
  3. DOS window
This is the default setting. Using the 'Properties' option on the System Menu, an option has been added called 'Touch: exclusive to a window' which disables mouse emulation under PM and gives the touch x,y,z data directly to the window designated. The window will, however, receive full screen touch coordinates and will need to perform a mapping unless, for example, it is a graphics program running maximised which covers the full screen.

In these cases mouse emulation mode must be used.

Q. What happens when a DOS program is started in a window and then switched to full screen?

Q. And can a full screen program be switched to a window?

For answers to these questions see the discussion under "INT 7Fh support."

Mouse Emulation

Mouse emulation is performed by the combined touch/mouse device dependent driver, where instead of reporting touch event x,y,z data to the TOUCH.SYS driver, the touch event is converted into an equivalent mouse event and reported to the MOUSE.SYS driver.

To allow this to happen, the MOUSE.SYS driver has two IDC entry points for the reporting of data, one being the conventional entry point where real mouse events are reported, the other where an absolute pointing device such as the touch screen can call directly with absolute x,y values instead of the normal dx,dy relative mouse movement (in Mickeys) values.

The emulation is being performed at the junction between the device dependent and independent drivers, so that at the interfaces of the MOUSE.SYS driver which are exposed to the outside world (IOCtl, MouXXX API, INT33h API), no difference can be detected between the emulated mouse device and a real mouse device. The device independent driver is just that - it hides the differences between the different sorts of mice that can attach to the system, which may in fact be real mice, or could equally be tracker balls, tablets, touch screens, light pens - or even a voice recognition system!

This implementation also allows flexibility in that the mouse and touch screen may be used independently, the touch screen may be used on its own to emulate the mouse (though without button 2 capability), or the touch screen may be used to emulate the mouse with simultaneous use of the IBM PS/2 Mouse itself.

Differences:

OS/2 2.0 support and OS/2 1.2/3 support.

  1. Mouse emulation is no longer performed on a 'per session' basis. Mouse emulation is now on or off system wide, turning mouse emulation off using the Touch Control Panel will affect all other sessions.

    VDM's do, however, have individual mouse emulation states: which means that if mouse emulation is on system wide, VDM's can choose to have mouse emulation on or off individually (this is because the DOS INT7Fh API has its own mouse emulation on/off control function, and we want to virtualise this on a per VDM basis, so turning mouse emulation off in one VDM does not affect the emulation state in another).
  2. Mouse emulation is available when the touch display device is reporting touch data: opening of the touch device turns off mouse emulation by default, but mouse emulation may be turned back on while the device is still open as a touch device. Each touch event then becomes two events: one touch and one emulated mouse event.

    This facility was available, but using an extra bit in the TouSetEmulOnOff() input parameter. It was also further complicated by the fact that, for a given session, there were two independent sets of hardware parameters: touch and mouse emulation, where, for example, different touch thresholds could apply in a session depending on whether mouse emulation was active or not). The new system is much cleaner to implement and easier to understand in this respect.

Device Driver Installation

The touch display shares the auxiliary device (mouse) port on the PS/2 with the IBM PS/2 Mouse by allowing the IBM PS/2 Mouse to connect to the touch display which is itself connected to the PS/2.

With the IBM PS/2 Mouse and touch display connected to the auxiliary device port, existing IBM PS/2 Mouse ABIOS and device drivers will continue to function as normal, requiring no changes.

However, to access the touch display via the touch display device driver, the following must be done:

  1. IBM PS/2 Mouse ABIOS must be replaced/extended
    This is done by using an ABIOS RAM extension contained in the file TOUMOUSx.BIO. The system file ABIOS.SYS needs to be modified to include this file in its list of ABIOS extensions. This ABIOS extension adds one function to the mouse ABIOS interface to allow the touch display to be controlled.
  2. device dependent IBM PS/2 Mouse driver must be replaced
    The DD file PDIMOU02.SYS is replaced by PDITOU02.SYS. This is done by modifying the entry in CONFIG.SYS (see below).
  3. CONFIG.SYS entries for the mouse are modified
    An entry for the combined mouse/touch device dependent driver is made:
    Format DEVICE=PDITOU0x.SYS CODE=TOUCO21D.BIN INIT=TOUCH.INI
    where TOUCO21D.BIN is the Touch Display microcode binary file
    TOUCH.INI is a text file containing default parameter settings

The following table describes the CONFIG.SYS DEVICE= keyword parameters for the combined mouse/touch device dependent driver.

Keyword Function Parameter Range Default
CODE= Microcode file to download into Touch Display valid filename none
INIT= Parameter file to over-ride default settings in device driver valid filename none

An entry for the touch device independent driver is made:

Format       DEVICE=TOUCH.SYS TYPE=PDITOU$ [QSIZE=] [SEL=]
Example      DEVICE=TOUCH.SYS TYPE=PDITOU$ QSIZE=15

An entry for the mouse device independent driver is made:

Format       DEVICE=MOUSE.SYS TYPE=PDIMOU$ [QSIZE=]
Example      DEVICE=MOUSE.SYS TYPE=PDIMOU$ QSIZE=15

Note that the device type must be PDIMOU$.

The entry for the device dependent mouse/touch device driver must precede the other two entries, for which the order of appearance is not important.

The following table describes the common CONFIG.SYS DEVICE= keyword parameters for the device independent mouse and touch drivers.
  Keyword      Function                Parameter Range          Default
  ---------------------------------------------------------------------
  QSIZE=       OS/2 mode support       1 - 100 elements         10
               event queue size in
                  elements
  ---------------------------------------------------------------------
  TYPE=        Indicates device        PDITOU$ for touch
               (dependent) name        PDIMOU$ for mouse
The following table describes the unique CONFIG.SYS DEVICE= keyword parameters for the touch device independent driver.
  Keyword      Function                Parameter Range          Default
  ---------------------------------------------------------------------
  SEL=         Selection mechanism     Selection type  0-5       0
               in protected and real   # of stable points 0-40
               mode                    Tolerance value 0-4095
                                          Search Limit 0-40
An entry for the touch virtual device driver is made:
Format DEVICE=VTOUCH.SYS
Example DEVICE=VTOUCH.SYS
There are no keyword parameters for the touch virtual device driver.
An entry for the mouse virtual device driver is made:
Format DEVICE=VMOUSE.SYS
Example DEVICE=VMOUSE.SYS

Note that the handling of threshold parameter changes, filter frequencies and click locking parameters is either done through the PM Touch Control Panel (see "Touch Control Panel") or the TOUCH.INI parameter file (see below).

FORMAT OF TOUCH.INI PARAMETER FILE

A TOUCH.INI parameter file is supplied containing the defaults device driver settings for:

  • Force Thresholds
  • Mouse emulation on|off control
  • Mouse emulation beep feedback (on button down) on|off control
  • Mouse emulation Click lock parameters
  • Mouse emulation XY finger - pointer offset
  • Data packet report rate
  • Low pass filter setting

The file contents over-ride the built in device dependent driver settings using the 'INIT=filename' keyword in the DEVICE= config.sys entry for the device driver.

Any file may be used if it conforms to the TOUCH.INI syntax: the Touch Control Panel will use and update the same file referred to by the config.sys entry.

The following shows the format of the TOUCH.INI file containing the default settings:

  /*
   * TOUCH.INI - 8516 Touch Display Device Dependent
   * Driver Initialization File
   *
   */

  /* The format of this file is as follows:
   *
   * One Key Word per line followed by an equals sign then the arguments,
   * no duplicate tokens allowed
   *
   * All spaces & tabs are ignored
   * Arguments are delimited with commas
   *
   * To set an option OFF use 0
   * To set an option ON  use 1
   *
   * Two types of comment are supported.
   * They conform to the 'C' programming
   * language syntax. Nested comments, in any form, are not supported.
   *
   */

THRESH  = 46, 80, 96    // Thresholds [on-screen, push-hyst, push-thresh]
CLICK   = 2, 300, 500   // Click Locking [type, size, time]
XYOFF   = 0, 0          // XY Offset [x-off, y-off]
RATE    = 3             // Report Rate [rate]
EMUL    = 1             // Mouse Emulation [on/off]
BEEP    = 1             // Emulation Beep on selection [on/off]
FILT    = 0, 0          // Low pass filter type, speed
//MPI   = 200           // (internal use only!)

  /* end-of-file */
</tt>
==CALIBRATION UTILITY INSTALLATION==
The calibration utility performs the dual function of downloading calibration constant data to the touch display every time the system unit is powered on and allowing re-calibration of the touch display (on initial setup, when the display is moved to a new location etc.).

For this reason it should be inserted into the config.sys file where it will run automatically every time the system unit is powered on (or
indeed warm booted, although this is not strictly necessary).  An entry in config.sys is made so:
     run=c:\touchos2\calibrat.exe -c calibrat.dat
If the calibrat.dat file is not found (when the display is initially installed for instance), the
operator will be prompted for action to re-calibrate the display, and if successful a new
calibrat.dat file will be created.

The calibration utility may be run from the OS/2 command line at any time, for example to re-calibrate the display:
     c:
     cd \touchos2
     calibrat -u
Note the use of the '-u' option which will allow an existing calibrat.dat file to be updated with new calibration data.

Presentation Manager and Touch: A Guided Tour

Unlike the PS/2 mouse, there is no in-built support for a Touch device in PM. This has implications both for true PM applications and
also full-screen applications that wish to become window-able. There are further complications when multiple DOS applications become window-able.

==Past History: The Mouse==
To begin with, let us consider what has been done with the mouse.

;OS/2 1.0

With OS/2 1.0, only full screen applications were possible, each running in a separate screen group. The application made use of the MouXXX calls API (or INT33h API if running in the DOS 3.x compatibility box), and was able to behave as though it were the only application using the mouse.

The Mouse device driver maintained a separate state for each screen group, so that when switching between screen groups, it would save and restore the states appropriate for each screen
group. In this way, applications were isolated from each other and able to operate without mutual interference.

Only the foreground screen group, however, was permitted access to the mouse: any application making an MouXXX call while running detached in the background would have the call fail with an error.

;OS/2 1.1

With OS/2 1.1 came the Presentation Manager screen group, where multiple applications can be run in one screen group, under the overall control of the Presentation Manager desktop/shell. The application could either be a new application, written to use the new PM API, or it could be a port of an existing full-screen text application working within a PM text window. Full-screen applications could still run in a separate full-screen screen group as before in OS/2 1.0.

To run in a PM window, however, text mode applications had to conform to certain restrictions and rules. Essentially, these preclude any action by one program in the PM screen group having an unintended adverse effect on any other, including the PM shell itself, and other text window applications or true PM applications. These restrictions affect not only the mouse, but also the keyboard and screen I/O where similar restrictions apply.

To accomplish this, the PM shell assumes responsibility on behalf of all the applications running under it for the Mouse device, in terms of how the mouse and associated device driver is
configured (eg absolute coordinate report range, scaling factor, pointer image shape etc.). It does this by providing a replacement mouse subsystem for that screen group to handle the
MouXXX calls that applications may make. It can then control the way in which the application has access to the Mouse device.

(Note that applications which do not conform, for example by direct IOCtl commands to the device driver, or (??#@%$!) commands direct to the hardware are likely to cause unpredictable
behaviour of the Mouse device within PM as a whole).

Applications written to the PM API would not normally make any MouXXX calls (although they are not explicitly stopped from doing so, for example to query the number of buttons the mouse has), rather they rely on receiving messages from PM indicating when the users mouse input is directed at them as a window rather than any other program running or the PM shell itself.

One of the consequences of running in a window is that the physical screen coordinates and application coordinates do not coincide, as the application window may be moved or sized to any
position on the screen. However, the PM shell has the information required to accomplish the transformation, so that applications, including text window applications are given the correct
coordinates.

Effectively the 'state' of the mouse and mouse driver is fixed for all applications running under PM. As an example, the mouse device driver is configured by PM to return data in absolute
coordinate reporting format: any text window program requiring data in relative reporting format will find it is unable to make the Mou call successfully to accomplish this. To allow the
call would cause PM to lose track of where the mouse pointer was, thereby creating havoc.

In this way then the PM screen group manages to run several applications at once, all able to use the mouse device, as well as itself. It does this at the expense of allowing each application total control over the mouse device which it was previously able to enjoy when running in a separate full-screen screen group.

==Today: The Touch Device==
FULL-SCREEN SCREEN GROUP

For the Touch device things are no different than they are for the mouse where applications running in a full-screen screen group are concerned. There is a TdiXXX (Int 7Fh in the DOS box) API which provides full access to the device hardware. Applications are isolated from each other by running in a separate screen group, the state of which is maintained separately by the device driver, which saves and restores the states as screen group switching takes place.

PRESENTATION MANAGER SCREEN GROUP

In PM there is one problem to be addressed:
# PM does not acknowledge the existence of any other input devices other than keyboard and mouse.

This gives rise to two sub-problems:
# How to drive the PM shell itself with an input device other than the keyboard or mouse?
# How to allow applications concurrent use of the Touch device if PM is not in complete control as it is with the mouse?

The issue can be sidestepped by providing an emulation of the Mouse device by the Touch device.
This has the advantage that all existing applications that currently use the Mouse will work with Touch (including the PM shell). This assumes that all Mouse actions can be emulated by
the Touch device. It may not be the case as in:
* No provision for button 2 emulation (button 2 now being defined by CUA for direct manipulation).
* Double clicking may be difficult to achieve in practice (requirement for a stable x,y position being a particular problem).

This problem can be circumvented to some extend by use of 'click locking' which effectively performs the task of locking the touch coordinates onto a single value when button clicking is being attempted.

Alternatively, a solution may be sought that does not involve a change to PM. One approach is to write a 'Touch manager' component that assumes control of the Touch device, perhaps replacing the subsystem to prevent direct access to the device. The Touch manager then processes the touch data events, issuing new style Touch messages as well as Mouse messages to PM applications, Mouse/System messages to the PM shell/control windows and also providing Touch coordinate data to windowed text applications (suitably transformed to take account of window sizing and placement).

One solution in this vein (AUI) clearly worked, but the developers still felt that the only real solution was an open architecture scheme for the input device management of PM that would allow support for all current input devices as well as extensibility for future devices.

IBM PS/2 8516 TOUCH DISPLAY POSITION

Currently IBM PS/2 8516 Touch Display offers what might be termed a 'reasonable' attempt at mouse emulation (but no button 2), where mouse movement, button clicking, dragging and double clicking are all possible.

As far as full touch mode is concerned, any application has full access to the Touch device, bearing in mind that since there are no restrictions placed on the TdiXXX calls that may
be made, applications have to be self-regulatory, otherwise they may conflict. Note, however, that if PM were 'Touch aware', it would be making a similar set of restrictions on the use of the TdiXXX API as it does with the MouXXX API, so nothing is effectively being lost in this respect.

Even the ability to write a PM application using the Touch device in the same manner as the Mouse device (via messages) is available to the application by writing a 'Touch manager' either as part of the application or stand alone using private messages.

TOUCH APPLICATIONS IN PM

An existing product which supports Touch input in PM, Executive Decisions, has already shown that the requirements for Touch are different than for Mouse (icons/selection items must be larger, program runs as a PM window occupying the full screen with the user never having to see the normal PM desktop).

This indicates that the 'solution' for Touch in PM, if such a thing exists, not only involves changes to the PM architecture to allow new input devices, but also the appearance of the desktop (eg allow scroll bar size to be configured when sizing a window) and the way in which it can be manipulated (CUA definitions for keyboard and mouse to extended certainly for touch, and perhaps also to include a 'generic' input device type (which could be the mouse)).

===Design notes===

===CURRENT STATE OF AFFAIRS: OS/2 1.2/3===
The parameters which can be affected by the touch API's are on a per-session basis (including DOS 3.x box session). For each session, the device driver holds a local set of parameters for such things like: thresholds, coordinate system, event mask, click lock mechanism, selection detection mechanism etc.

For those parameters which actually cause a change of state of the hardware (eg thresholds, filter type etc.), for every session switch the outgoing session's current parameters are saved and the incoming session's parameters are restored by sending commands to the touch display to effect the changes.

While this is a most flexible arrangement, allowing separate full screen sessions completely different settings for such things as touch thresholds, it becomes impossible to provide
support for separate programs running in windows under Presentation Manager.

The current situation allows programs running under Presentation Manager (either AVIO text windowed or full PM programs) full access to the TouXXX API, along with the ability for each
program to unilaterally change the touch thresholds, coordinate system etc. Since these functions directly change the state of the hardware, we have the situation where programs sharing the same output device (screen) are allowed parallel access to a single input device.
Result: chaos (or complete flexibility, depending on how you view it)!

===CHANGES FOR OS/2 2.0===
What is needed is a single owner of the device (PM) which them handles it on behalf of its multiple clients. However, until PM changes to support multiple input devices in the way that it
currently only handles keyboard and mouse, nothing is likely to alleviate this situation.

Thus the implementation carries over the dual full touch/mouse emulation nature of the touch device support, leaving it up to the application developer to choose how they wish to use the touch device.

However, some changes have been made to get round some of the other problems noted with the OS/2 1.2/3 implementation, and to accommodate the new features of OS/2 2.0: namely MDVM support.

TRUE DEVICE INDEPENDENT TDIXXX API

It was decided to scrap the ability to access all the hardware dependent features of the original TouXXX API and design a new device independent TdiXXX API.

The facility for changing the hardware by an application has been removed with &cruiser, so that an application program no longer has the ability to unilaterally change the touch
thresholds, coordinate system etc. to the detriment of other applications running at the same time.

Thus, the TdiXXX API no longer allows access to hardware dependent features, and indeed, those hardware dependent calls in the TouXXX API which is also provided for compatibility with OS/2 1.2/3 are either virtualised or are no-ops. In either case, the hardware state is unaffected by these calls , so that the state of the hardware is fixed, and can only be altered by using the Touch Control Panel once the device drivers are loaded.

MULTIPLE VIRTUAL DOS MACHINE (MVDM) SUPPORT

The OS/2 1.2/3 driver followed the same model as the mouse device driver in providing DOS box support of the DOS device driver INT7Fh API in the same way that INT33h is also supported by the mouse device driver.

In the same way, the IBM PS/2 8516 Touch Display support for OS/2 2.0 includes a virtual device driver which gives a (virtualised) DOS INT7Fh API for MVDM's. Touch events are simulated in the VDM using IRQ12/INT74 which is shared with the VMOUSE.SYS when using a PS/2 mouse. The extensions to PS/2 mouse BIOS (INT15 AH=C2h) for touch are not supported in any way.

When considering the problems concerned with accessing the touch device in Presentation Manager, with OS/2 2.0 the problem extends to DOS programs running in a window under Presentation
Manager. The virtual device driver provided will support the DOS INT7Fh API for MVDM's, but by default will be limited to making actual touch x,y,z data available to full screen DOS programs only. This is because while running with the Presentation Manager session in the foreground, the physical device driver, which handles the touch data interrupts, cannot decide on its own which window to send the touch data to.

The mouse accomplishes this because it is able to feed the PM single queue, then PM decides, based upon the event x,y data, which window is to receive the event. If this is a DOS window, it calls the virtual device driver.

For those DOS applications that nevertheless wish to receive full screen x,y,z touch data while running in a window, a DOS property will be provided ('Touch: exclusive to a window') which
will effectively turn off mouse emulation and direct all touch data to that window.

This then solves the question of what happens with applications that can be switched between full screen and windowed - the answer being that while the (now device independent) DOS INT7Fh API will continue to function in a window, touch data will not be available to the application until it is switched to full screen. In all other respects the application will function exactly as before.

DOS mouse applications will, however, not be subject to this restriction, being able to run with touch input in the form of emulated mouse data in a DOS window or full screen.

==OS/2 Device Independent Subsystem and API==

===Touch Device Independent Subsystem DLL===
The Touch device independent sub-system is contained in the TDICALLS.DLL run time file, executing on level 3 (application level). The sub-system receives all TDIxxx calls, passing them
to the Touch Device Independent Device Driver which receives control via DosOpen,Close or the DosDevIOCtl API.

The Touch sub-system is similar in many respects to the Mouse sub-system, except that it does not provide for registering/de-registering extensions to the subsystem.

===TDIXXX API===
A new Touch API is provided by the Touch device independent sub-system:
* TdiClose
* TdiFlushQueue
* TdiGetCoordSys
* TdiGetEmulState
* TdiGetEventMask
* TdiGetQueueSize
* TdiGetSelectMethod
* TdiOpen
* TdiReadEventQueue
* TdiSetCoordSys
* TdiSetEmulState
* TdiSetEventMask
* TdiSetQueueSize
* TdiSetSelectMethod
Refer to the file TDICALLS.H for C function prototypes, structures and #defined constants useful for this API.

===TDICLOSE===
This call closes the touch device for the current session.
 TdiClose(DeviceHandle, rc)

;INPUT PARAMETERS
 Device Handle (HTDI)
 Handle of the touch device from a previous TdiOpen call

;OUTPUT
  rc (USHORT)
  Return code in register AX
    0 - NO_ERROR

===TDIFLUSHQUEUE===
This function directs the touch driver to flush (empty) the touch event queue for the session.
 TdiFlushQueue(DeviceHandle, rc)

;INPUT PARAMETERS
  Device Handle (HTDI)
  Handle of the touch device from a previous TdiOpen call

;OUTPUT
 rc (USHORT)
 Return code in register AX
   0 - NO_ERROR
       TDI_ERR_UNKNOWN_COMMAND
       TDI_ERR_GENERAL_FAILURE

===TDIGETCOORDSYS===
This function returns to the caller the current coordinate reporting range and hysteresis used in x,y reports.
 TdiGetCoordSys( CoordSys, DeviceHandle, rc)

INPUT PARAMETERS

         CoordSys   (PTDICOORDSYS)
        This is a pointer to a structure of type TDICOORDSYS in which the
         function returns the coordinate system:

         Offset      Type         Description

         0H          USHORT       X minimum value
         2H          USHORT       X maximum value
         4H          USHORT       Y minimum value
         6H          USHORT       Y maximum value
         8H          USHORT       Z minimum value
         AH          USHORT       Z maximum value
         CH          USHORT       X hysteresis value * 1000
         EH          USHORT       Y hysteresis value * 1000

         Device Handle (HTDI)
         Handle of the touch device from a previous TdiOpen call

OUTPUT
         rc (USHORT)
         Return code in register AX

             0 - NO_ERROR
                 TDI_ERR_UNKNOWN_COMMAND
                 TDI_ERR_GENERAL_FAILURE
Notes:

1.  Hysteresis is the amount, expressed in
    coordinate report units multiplied by 1000, by
    which a touch contact must cross the border
    between adjacent coordinate cells before a
    change in coordinate report is registered.

2.  This is to prevent reports flickering between
    two values when a touch contact point lies on
    the border of adjacent coordinate cells.

3.  A default hysteresis of 0.5 coordinate units
    (reported value of 500 using this function) is
    used.

4.  X,Y and Z values must be in the range -32768
    to +32767.  X axis will increase from left to
    right if Xmax >  Xmin, or become inverted if
    Xmin >  Xmax.  Z axis will increase from top
    to bottom if Ymax >  Ymin, or become inverted
    if Ymin >  Ymax.

5.  Hysteresis values are unsigned integers in the
    range 0 to 65535.

6.  Hysteresis values are expressed in terms of
    the required hysteresis value, in coordinate
    system units, multiplied by 1000.

7.  Thus to set a hysteresis of 0.5, a value of
    500 should be used.  The maximum hysteresis
    that may be set is therefore 65.535 screen
    units, corresponding to the maximum permitted
    value 65535.

===TDIGETEMULSTATE===
This function returns to the caller the current state of mouse emulation.
 TdiGetEmulState (EmulState, DeviceHandle, rc)

INPUT PARAMETERS

 EmulState (PUSHORT)
 This is a pointer to a structure of type USHORT in which the
 function returns the mouse emulation state:

 Bit     Description
 0       Mouse emulation state
         =0 = Emulation off, =1 = Emulation on
 1-F     Reserved (=0)

 Device Handle (HTDI)
 Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
 Return code in register AX

   0 - NO_ERROR
       TDI_ERR_PARAMETERS_INVALID
       TDI_ERR_UNKNOWN_COMMAND
       TDI_ERR_GENERAL_FAILURE
Notes:
# Under Presentation Manager any program which opens the Touch Display device (TdiOpen) disables mouse emulation for the whole of the Presentation Manager session. Mouse emulation can be enabled while the touch device is open using TdiSetEmulState(), whence touch data becomes available both as emulated mouse data as well as touch data.

===TDIGETEVENTMASK===
This function returns to the caller the current touch event queue mask.
 TdiGetEventMask(EventMask, DeviceHandle, rc)

INPUT PARAMETERS

 EventMask (PUSHORT)
 This is a pointer to a structure of type USHORT in which the
 function returns the event mask:

 Bit          Description

   0         1 = report On screen events (On Screen status set)
   1         1 = report Touch Down events (On Screen status clear to set)
   2         1 = report Lift Off events (On Screen status set to clear)
   3         1 = report Selection detection flag set events
   4         1 = report Selection Detection flag clear to set events
   5         1 = report Selection Detection flag set to clear events
   6-F       reserved

 Device Handle (HTDI)
 Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
 Return code in register AX

 0 - NO_ERROR
     TDI_ERR_PARAMETERS_INVALID
     TDI_ERR_UNKNOWN_COMMAND
     TDI_ERR_GENERAL_FAILURE

===TDIGETQUEUESIZE===
This function returns to the caller the current maximum number of elements allowed in a touch event queue. The maximum queue size itself is defined by the CONFIG.SYS QSIZE= parameter.
 TdiGetQueueSize(QueSize, DeviceHandle, rc)

INPUT PARAMETERS

 QueSize (PUSHORT)
 This is a pointer to a structure of type USHORT in which the
 function returns the current queue size:

 Offset      Type         Description
 0H          USHORT       Maximum size of the event queue

 Device Handle (HTDI)
 Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
  Return code in register AX

  0 - NO_ERROR
      TDI_ERR_PARAMETERS_INVALID
      TDI_ERR_UNKNOWN_COMMAND
      TDI_ERR_GENERAL_FAILURE

Notes:
# If the maximum number of elements in the queue have been altered by TdiSetQueueSize, then this function will reflect that as the new maximum.
# The number of touch events in the queue itself is returned with the TdiReadEventQueue call.

===TDIGETSELECTMETHOD===
This function returns to the caller the current status of the selection detection flag set/reset mechanism.
 TdiGetSelectMethod(SelectMech, DeviceHandle, rc)

INPUT PARAMETERS
 Selectmech (PTDISELMECH)
  This is a pointer to a structure of type TDISELMECH in which the
  function returns the selection detection flag set/reset mechanism.

  Offset      Type         Description

  0H          USHORT       Selection Type
                            Bit 0
                             0 = Push harder (default)
                             1 = Lift Off
                            Bit 1
                             0 = First value taken
                             1 = Single touch algorithm active
                            Bit 2
                             0 = First value taken
                             1 = Stable region algorithm active
                            Bit 3 - F
                             0 = Reserved

  2H          USHORT        Number of stable points
                              0 = default
                              n = # of stable points

  4H          USHORT        Tolerance value
                              0 = default
                              n = tolerance in pixels

  6H          USHORT        Stack length
                              0 = default
                              n = length in samples ( 0 < n < 60 )

  Device Handle (HTDI)
   Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
  Return code in register AX

  0 - NO_ERROR
      TDI_ERR_PARAMETERS_INVALID
      TDI_ERR_UNKNOWN_COMMAND
      TDI_ERR_GENERAL_FAILURE
Notes:

1.  With the simple first value push harder mode,
    the selection detection flag set on when touch
    pressure increases past the push threshold.
    Selection detection flag reset off when touch
    pressure decreases below the push hysteresis
    threshold.

2.  With the simple first value lift off mode, the
    selection detection flag is set and reset on
    consecutive data reports upon touch contact
    decreasing below the on screen threshold
    ('lift off').

3.  The selection detection flag state can be read
    using TdiReadEventQueue and examining the
    status in TDIEVENTINFO.

4.  For information on thresholds, see the
    associated functions TddSet/GetThresh.

===TDIOPEN===
This call opens the touch device for the current session.
 TdiOpen(DeviceHandle, rc)

INPUT PARAMETERS
         Device Handle (PHTDI)
         This is a pointer to HTDI into which the function will put
         the device handle

OUTPUT
 rc (USHORT)
  Return code in register AX

  0 - NO_ERROR
      TDI_ERR_PARAMETERS_INVALID
      TDI_ERR_NOT_CALIBRATED
      TDI_ERR_UNKNOWN_COMMAND
      TDI_ERR_GENERAL_FAILURE

Notes:
#  An open will reset the touch screen parameters settable via the TdiSetxxx calls to the default values.  An exception is mouse emulation which will be turned off regardless of the emulation state in the screen group before the TdiOpen call was made.
# This call will fail if the touch display has not been calibrated.

===TDIREADEVENTQUEUE===
This function reads an event from the touch display device driver FIFO event queue and places it in a structure provided by the application.
 TdiReadEventQueue(EventInfo, ReadType, DeviceHandle, rc)

INPUT PARAMETERS

 EventInfo (PTDIEVENTINFO)
  This is a pointer to a structure of type TDIEVENTINFO into
  which the function will place the event data.

         XYZ DATA

           Offset      Type         Description

           0H          USHORT       cEvents
           2H          USHORT       TouState
           4H          ULONG        EventTime  (event time stamp in ms)
           8H          USHORT       X Value
           AH          USHORT       Y Value
           CH          USHORT       Z Value


           cEvents
           Gives a count of the remaining number
             of events in the event queue
           after this event has been read.


           TouState
           Represents the state of the touch display at the
           time the event is reported.

          BIT      Description

           0         1 = On screen event (On Screen status set)
           1         1 = Touch Down event (On Screen status clear to set)
           2         1 = Lift Off event (On Screen status set to clear)
           3         1 = Selection detection flag set event
           4         1 = Selection Detection flag clear to set event
           5         1 = Selection Detection flag set to clear event
           6-F       reserved



         Read Type (PUSHORT)
         This is a pointer to a structure of type USHORT which indicates
         the action to take when the function is issued and the touch
         event queue is empty:

          0 = Return NULL EventInfo if data not available (NO WAIT)
          1 = WAIT for data on empty queue.
          2 = PEEK return event info but do not
              remove event from event queue


         Device Handle (HTDI)
         Handle of the touch device from a previous TdiOpen call

OUTPUT

  rc (USHORT)
   Return code in register AX

   0 - NO_ERROR
       TDI_ERR_PARAMETERS_INVALID
       TDI_ERR_UNKNOWN_COMMAND
       TDI_ERR_GENERAL_FAILURE

===TDISETCOORDSYS===
This function sets the current coordinate reporting range and hysteresis used in x,y reports.
 TdiSetCoordSys(CoordSys, DeviceHandle, rc)

INPUT PARAMETERS

 CoordSys   (PTDICOORDSYS)
  This is a pointer to a structure of type TDICOORDSYS which
  contains the coordinate system required:

  Offset      Type         Description
  0H          USHORT       X minimum value
  2H          USHORT       X maximum value
  4H          USHORT       Y minimum value
  6H          USHORT       Y maximum value
  8H          USHORT       Z minimum value
  AH          USHORT       Z maximum value
  CH          USHORT       X hysteresis value * 1000
  EH          USHORT       Y hysteresis value * 1000

  Device Handle (HTDI)
   Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
  Return code in register AX

  0 - NO_ERROR
      TDI_ERR_PARAMETERS_INVALID
      TDI_ERR_UNKNOWN_COMMAND
      TDI_ERR_GENERAL_FAILURE

Notes:
# Hysteresis is the amount, expressed in coordinate report units multiplied by 1000, by which a touch contact must cross the border between adjacent coordinate cells before a change in coordinate report is registered.
# This is to prevent reports flickering between two values when a touch contact point lies on the border of adjacent coordinate cells.
# A default hysteresis of 0.5 coordinate units (reported value of 500 using the TdiGetCoordSys() call) is used.
# X,Y and Z values can be in the range -32768 to +32767.
# Hysteresis values are unsigned integers in the range 0 to 65535
# Hysteresis values are expressed in terms of the required hysteresis value, in coordinate system units, multiplied by 1000.
# Thus a value of 500 indicated a hysteresis of 500/1000 = 0.5 screen units.  The maximum hysteresis that may be set is therefore 65.535 screen units, corresponding to the maximum permitted value 65535.

===TDISETEMULSTATE===
This function enables or disables mouse emulation.
 TdiSetEmulState (EmulState, DeviceHandle, rc)

INPUT PARAMETERS

 EmulState (PUSHORT)
  This is a pointer to a structure of type USHORT in which the
  function returns the mouse emulation state:

  Bit     Description
  0       Mouse emulation state
          =0 = Emulation off, =1 = Emulation on
  1-F     Reserved (=0)

 Device Handle (HTDI)
  Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
  Return code in register AX

  0 - NO_ERROR
      TDI_ERR_PARAMETERS_INVALID
      TDI_ERR_UNKNOWN_COMMAND
      TDI_ERR_GENERAL_FAILURE

Notes:
# Under Presentation Manager any program which opens the Touch Display device (TdiOpen) disables mouse emulation for the whole of the Presentation Manager session.  Mouse emulation can be enabled while the touch device is open using TdiSetEmulState(), whence touch data becomes available both as emulated mouse data as well as touch data.

TDISETEVENTMASK

This function assigns a new event mask to the current touch display device driver. The mask controls which data events from the touch display are inserted into the event queue (see also
"TdiReadEventQueue").
 TdiSetEventMask(EventMask, DeviceHandle, rc)

INPUT PARAMETERS

 EventMask (USHORT)
  This is a structure of type USHORT in which the caller supplies
  the required event mask:

  Bit          Description

    0         1 = report On screen events (On Screen status set)
    1         1 = report Touch Down events (On Screen status clear to set)
    2         1 = report Lift Off events (On Screen status set to clear)
    3         1 = report Selection detection flag set events
    4         1 = report Selection Detection flag clear to set events
    5         1 = report Selection Detection flag set to clear events
    6-F       reserved


  Device Handle (HTDI)
   Handle of the touch device from a previous TdiOpen call

OUTPUT
 rc (USHORT)
  Return code in register AX

  0 - NO_ERROR
      TDI_ERR_PARAMETERS_INVALID
      TDI_ERR_UNKNOWN_COMMAND
      TDI_ERR_GENERAL_FAILURE

TDISETQUEUESIZE

This function allows the maximum number of queued elements to be altered (subject to the limit set from the CONFIG.SYS QSIZE= parameter).
 TdiSetQueueSize(QueSize, DeviceHandle, rc)

INPUT PARAMETERS
 QueSize (USHORT)
 This is a pointer to USHORT which contains the required maximum
 number of queued elements in the Touch Device event queue:

 Offset      Type         Description
 0H          USHORT       Maximum number of elements in event queue
 Device Handle (HTDI)
 Handle of the touch device from a previous TdiOpen call

OUTPUT

 rc (USHORT)
 Return code in register AX

 0 - NO_ERROR
     TDI_ERR_PARAMETERS_INVALID
     TDI_ERR_UNKNOWN_COMMAND
     TDI_ERR_GENERAL_FAILURE

Notes:
# This function will return an error if an attempt is made to set the current number of event queue elements to greater than the maximum size set in the CONFIG.SYS QSIZE=parameter.
# If queue size input is set to zero, this will force the QSIZE= parameter value to be used as the current queue size. The minimum queue size which may be set using this function is therefore 1.


TDISETSELECTMETHOD

This function sets the selection detection flag set/reset mechanism.
 TdiSetSelectMethod(SelectMech, DeviceHandle, rc)


INPUT PARAMETERS

         Selectmech (PTDISELMECH)
         This is a pointer to a structure of type TDISELMECH which
         contains the required selection detection
         flag set/reset mechanism.


         Offset      Type         Description

         0H          USHORT       Selection Type
                                   Bit 0
                                      0 = Push harder (default)
                                      1 = Lift Off
                                   Bit 1
                                      0 = First value taken
                                      1 = Single touch algorithm active
                                   Bit 2
                                      0 = First value taken
                                      1 = Stable region algorithm active
                                   Bit 3 - F
                                      0 = Reserved

         2H          USHORT        Number of stable points
                                    0 = default
                                    n = # of stable points

         4H          USHORT        Tolerance value
                                    0 = default
                                    n = tolerance in pixels

         6H          USHORT        Stack length
                                    0 = default
                                    n = length in samples ( 0 < n < 60 )

         Device Handle (HTDI)
         Handle of the touch device from a previous TdiOpen call

OUTPUT

         rc (USHORT)
         Return code in register AX

             0 - NO_ERROR
                 TDI_ERR_PARAMETERS_INVALID
                 TDI_ERR_UNKNOWN_COMMAND
                 TDI_ERR_GENERAL_FAILURE

Notes:
# With the simple first value push harder mode, the selection detection flag is set (=1) when touch force rises above the push threshold. Selection detection flag is reset (=0) when touch pressure falls below the push hysteresis threshold.
# With the simple first value lift off mode, the selection detection flag is set and reset in consecutive data reports upon touch contact force falling below the on screen threshold ('lift off').
# The selection detection flag state can be read using TdiReadEventQueue and examining the status in TDIEVENTINFO.

TDIXXX RETURN CODES
 0 - NO_ERROR
     TDI_ERR_NOT_CALIBRATED
     TDI_ERR_PARAMETERS_INVALID
     TDI_ERR_UNKNOWN_COMMAND
     TDI_ERR_GENERAL_FAILURE

Apart from the not calibrated return code, these are aliases of the OS/2 DosDevIOCtl return codes.

==OS/2 DEVICE DEPENDENT API==
The following table shows the new TDDXXX API which will not be exposed to new applications, being used mainly by the calibration utility (requires access to raw data and download calibration constant functions) and the Touch Control Panel (to set hardware dependent features such as touch thresholds, filters etc.):
 TDDClose
 TDDDldCalibConsts
 TDDGetCalibConsts
 TDDGetClickLockData
 TDDGetEmulXYOffset
 TDDGetFilter
 TDDGetRepRate
 TDDGetThresh
 TDDOpen
 TDDReadData
 TDDReadMem
 TDDSetClickLockData
 TDDSetEmulXYOffset
 TDDSetFilter
 TDDSetMode
 TDDSetRepRate
 TDDSetThresh
 TDDWriteMem
This interface is not intended to be exposed to the outside world, rather as just a convenient means for the Touch Control Panel to access the hardware without using direct DosDevIOCtl calls

===TOUXXX API COMPATIBILITY===
For completeness, the following table gives the complete API calls, including those provided for compatibility (but not exposed as part of the new API), and those which were never originally exposed and were part of the TouXXX API, which will be moved to a new device dependent TDDXXX API (also not exposed).

         Device Independent                 Device Dependent

         TouClose                           TDDClose
         TouFlushQue                        TDDGetCalibConsts
       * TouGetCoordOrg                     TDDDldCalibConsts
       * TouGetCoordSys                     TDDReadMem
       - TouGetDevStatus                    TDDWriteMem
         TouGetEmulOnOff
         TouGetEventMask
         TouGetNumQueEl                  TDDReadData (raw/xyz for calib)
         TouGetSelectMech
         TouOpen                        TDDOpen  (only one handle, cuts
         TouReadEventQue                             touch data supply to
         TouResetEmulState                          TOUCH.SYS + MOUSE.SYS)
       * TouSetCoordOrg
       * TouSetCoordSys                     TDDSetMode  (raw/xyz)
         TouSetEmulOnOff
         TouSetEventMask
         TouSetNumQueEl
         TouSetSelectMech

       # TouGetClickLockData                TDDGetClickLockData
       # TouGetFilter                       TDDGetFilter
       # TouGetRepRate                      TDDGetRepRate
       # TouGetThresh                       TDDGetThresh
       # TouSetClickLockData                TDDSetClickLockData
       # TouSetFilter                       TDDSetFilter
       # TouSetRepRate                      TDDSetRepRate
     * # TouSetThresh                       TDDSetThresh
       # TouQueryParms
       # TouSelectParms

       # TouGetXYOffset                     TDDGetEmulXYOffset
       # TouSetXYOffset                     TDDSetEmulXYOffset

Notes on new API:
       Only device dependent functions have effect on hardware state.

Key:

     # indicates provided for compatibility only.  Not virtualised
       and therefore have no effect on driver or hardware state.
       For each function not virtualised there is a companion (new)
       TDDxxx function to perform this device unique/dependent
       function.  Effects of these functions will be session wide.

     * indicates function virtualised in driver a with no effect
       on hardware state

       For thresholds the on screen threshold can be virtualised
       only to a limited degree, namely that the virtualisation
       may not be completely transparent to the end user (eg if
       a low on screen  threshold is set by the application the
       user may not 'feel' the difference.)

     - indicates this function has been removed altogether.

===DOS DEVICE DEPENDENT API===
Data via the DOS touch INT7Fh API will only be
available to DOS programs running full screen not
in a PM window.  All other functions not involving
data will operate correctly.

Note that, however, if mouse emulation is turned
on in a DOS session, the application can then
receive touch input in the form of emulated mouse
input when running in a DOS window under PM.
<pre>
 Software Interrupt INT 7Fh

 On Entry:
           AX = ABCDH
           BX = 0H

 On Exit:
           (CY) - 0 operation successful
                - 1 operation unsuccessful
           ES:BX points to a table of far call entry points:

           AX = Total number of functions available.

 Offset    Function                        Compatibility (not exposed)

    00H  - Installed flag and Reset
    04H  - Mouse emulation Reset
    08H  - Mouse emulation off/on
*   0CH  - Set coordinate system
*   10H  - Set coordinate origin
    14H  -                                 Set thresholds
    18H  - Set selection mechanism
    1CH  -                                 Set data report rate
    20H  - Set data block mask
    24H  - Get touch down information
    28H  - Get lift off information
    2CH  - Get selection turned on information
    30H  - Get selection turned off information
    34H  - Get current position and status
    38H  - Set User-defined Subroutine
    3CH  - Swap User-defined Subroutine
    40H  - Set filter type and cut off frequency
    44H  - Query Save State storage requirements
    48H  - Save Driver State
    4CH  - Restore Driver State
    50H  - Get Mouse emulation state
    54H  - Get Mouse emulation off/on
*   58H  - Get coordinate system
*   5CH  - Get coordinate origin
    60H  - Get thresholds
    64H  - Get selection mechanism
    68H  - Get data report rate
    6CH  - Get data block mask
    70H  - Get filter type and cut off frequenc                                 y
    74H  - Get driver/microcode level
    78H  - Get click lock data
    7CH  - Set click lock data

Figure 2. INT 7FH, AX=ABCDH, BX=0H. touch display interface functions

TOUCH CONTROL PANEL

A Presentation Manager Control Panel type program will provide the primary point of access to device dependent features, as well as some device independent ones. These are for IBM PS/2 8516 Touch Display:

o Mouse emulation only

   This affects the PM desktop session as well as
   the OS/2 full screen sessions.  The DOS
   sessions have individual mouse emulation
   control (via INT7Fh API or using the
   DEVUTIL.EXE DOS developers utility.
   1.  Mouse pointer XY offset
   2.  Mouse emulation button down sound/beep
       feedback on|off control
   3.  Mouse emulation Button/Click locking
       parameters
   4.  Mouse emulation on|off control

o Full touch mode and mouse emulation mode

   These settings affect the touch device as a
   whole and therefore affect all sessions, be
   they PM, OS/2 full screen or DOS full screen.
   1.  Touch force thresholds
           On screen threshold
           Button down (selection on in full
           touch) threshold
           Button up (selection off in full
           touch) threshold
   2.  Filter type/ cutoff frequency
   3.  Touch data packet report rate

It should be noted that only one set of values for hardware dependent parameters is in operation between mouse emulation mode and full touch mode, as well as across all sessions. This is to ensure that there is one consistent set of parameters active for the touch device, regardless of which session and under which mode it may be used.

(This is to be contrasted with the situation with the OS/2 1.x support, where different settings could be active for mouse emulation mode and full touch mode for each session.)

For this reason, the distinction between mouse emulation parameters and full touch parameters can be removed, with no need in the control panel to distinguish, for example, between the On screen threshold, or the filter type, set for full touch mode and that set for mouse emulation mode.


Inter-Device Communication Interfaces (IDC's)

DEVICE INDEPENDENT TO DEVICE DEPENDENT

The IDC provided by the device independent device driver consists of the following functions:

  • Process packet
  • Disable Support

PROCESS PACKET

This function is called by the device dependent driver when it has completed receiving and formatting touch device data into the shared data buffer address, so that the data may then be processed by the device independent driver.

Input:

   AX= Function Request code =0001H
   SI= shared data buffer offset
   DS= device independent driver's DS value
   ES= device dependent driver's DS value
   (caller)
   BX,CX,DX, and DI register contents are
   undefined

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   DS= device independent driver's DS value
   ES= device dependent driver's DS value
   (caller)
   BX,CX,DX,SI and DI register contents are
   undefined

DISABLE SUPPORT

This function is used by the device dependent device driver to inform the device independent driver that it has received a Deinstall request and wishes to release its system resources. The device independent driver cannot deinstall itself at this point, but it can disable the API interfaces.

Input:

   AX= Function Request code =0002H
   DS= device independent driver's DS value
   ES= device dependent driver's DS value
   (caller)
   BX,CX,DX,SI and DI register contents are
   undefined

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   DS= device independent driver's DS value
   ES= device dependent driver's DS value
   (caller)
   BX,CX,DX,SI and DI register contents are
   undefined

DEVICE DEPENDENT TO DEVICE INDEPENDENT

The IDC provided by the mouse component of the device dependent device driver is identical to that provided by a PS/2 mouse device dependent driver, with 2 exceptions: Enable and Disable device functions do not enable/disable the device at the IRQ level (which would cause the touch device to be simultaneously enabled/disabled), but simply stop/start reporting of data to the device independent driver.

The IDC provided by the touch component of the device dependent device driver consists of the following functions:

  • Query Configuration
  • Enable Read
  • Disable Write
  • Enable Device
  • Disable Device
  • Set Emulation State

QUERY CONFIGURATION

Input:

   AX= Function Request code =0001H
   DI= config data buffer offset
   DS= device dependent driver's DS value
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX, and SI register contents are
   undefined

ES:DI points to a data structure which is filled in by the device dependent driver to convey configuration information back to the device independent driver, according to the following format:

         config_data struc
                     length    dw ?  ; length (inclusive) of structure in bytes
                     irq_num   db ?  ; interrupt request level for device
                     mou_stat  dw ?  ; mouse device status flags
                                     ; bit 0 =1 Physical PS/2 mouse attached
                                     ; bit 1 =1 Device independent driver attached
                                     ; bit 2 =1 Protected mode emulation enabled
                                     ; bit 3 =1 Real mode emulation enabled
                     tou_stat  dw ?  ; touch device status flags
                                     ; bit 0 =1 Touch device calibrated
         config_data ends


Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   DI= config data buffer offset
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI and DS register contents are
   undefined


ENABLE READ

This function is issued by the device independent driver to indicate that data packet processing has been set up and data transfer may begin.

Input:

   AX= Function Request code =0002H
   DI= shared interrupt data buffer offset
   DS= device dependent driver's DS value
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX, and SI register contents are
   undefined

ES:DI points to the interrupt data packet structure in which the called device driver will write/return the touch data packet when a complete packet has been accumulated.


         touch_data struc
                     status    dw ?  ; touch display status
                     x_coord   dw ?  ; x coordinate of touch
                     y_coord   dw ?  ; y coordinate of touch
                     z_coord   dw ?  ; z coordinate of touch
                     x_range   dw ?  ; Xmax - Xmin
                     y_range   dw ?  ; Ymax - Ymin
                     z_range   dw ?  ; Zmax - Zmin
         touch_data ends


Note: X,Y,Z coordinates are reported in fixed 4096x4096x255 coordinate space. X increases left to right, Y increases top to bottom.

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI,DI and DS register contents are
   undefined


DISABLE WRITE

This function is called by the device independent driver to indicate that data packet processing is no longer supported and that data transfers via Process Packet should be stopped until a Enable Read request is processed. Following this call no further references should be made to the shared interrupt data buffer address previously provided via the last Enable Read request.

Input:

   AX= Function Request code =0003H
   DS= device dependent driver's DS value
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI and DI register contents are
   undefined

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI,DI and DS register contents are
   undefined

ENABLE DEVICE

This function is used to enable the touch data event reporting from the device dependent driver to the device independent driver. It does not affect interrupt data processing at the IRQ level (which is shared between PS/2 mouse and touch devices), therefore mouse data event processing and reporting is not affected.

Input:

   AX= Function Request code =0004H
   DS= device dependent driver's DS value
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI and DI register contents are
   undefined

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI,DI and DS register contents are
   undefined

DISABLE DEVICE

This function is used to disable the touch data event reporting from the device dependent driver to the device independent driver. It does not affect interrupt data processing at the IRQ level (which is shared between PS/2 mouse and touch devices), therefore mouse data event processing and reporting is not affected.

Input:

   AX= Function Request code =0004H
   DS= device dependent driver's DS value
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI and DI register contents are
   undefined

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,SI,DI and DS register contents are
   undefined

SET EMULATION STATE

This function is used to control the way that touch data packets are handled by the device dependent driver. When emulation mode is set to off, touch data packets are only reported to the touch device independent driver as direct x,y,z data packets. When mouse emulation mode is set to absolute, the touch data packet is additionally converted into a mouse data packet of absolute x,y form, and reported to the mouse device independent driver via its Process Packet Absolute IDC entry point. When mouse emulation mode is set to relative, the touch data packet is additionally converted into a mouse data packet of relative dx,dy form, and reported to the mouse device independent driver via its standard Process Packet IDC entry point.

Input:

   AX= Function Request code =0006H
   BX= Emulation mode (0=off 1=absolute
   2=relative)
   DS= device dependent driver's DS value
   ES= device independent driver's DS value
   (caller)
   CX,DX,DI and SI register contents are
   undefined

Output:

   AX= Error return code (if carry set, undefined
   if carry clear)
   ES= device independent driver's DS value
   (caller)
   BX,CX,DX,DI,SI and DS register contents are
   undefined

PHYSICAL DEVICE DRIVER TO VIRTUAL DEVICE DRIVER

The primary function is to communicate touch data packets to the virtual device driver. Unlike the virtual mouse driver, which can also receive mouse data from the PM shell so that DOS windows receive mouse data correctly adjusted for window size and position, this is the only route for touch data into the virtual device driver. Because of the lack of cooperative PM support in the way the mouse gets data, DOS windows are unable to receive touch data correctly adjusted for window size and position. Normally. therefore, a VDM will only receive touch data when it is running full screen (ie non-PM foreground session). In the PM session, all touch data will be used to form emulated mouse packets and reported to the Physical Mouse Driver. The Virtual Mouse Driver will then receive emulated mouse data via the normal PM shell route (or via Physical Driver route if exclusive mouse access 'on').

However, by using the 'Exclusive touch access' DOS property, a window can receive all touch data when running in the PM session. Since the data is in the form of full screen coordinates, a DOS window must effectively be run maximised (except for text mode applications where maximising a window does not cover the full screen) to run without modification (else it would have to perform the coordinate conversion itself, which is surely an impossible task for a DOS program since it has no knowledge of, or access to, window position/size information.

The PDD is passed the VDD entry point as a consequence of the VDD calling VDHOpenPDD with the 16:16 address of VTEventProc as parameter.


VTEVENTPROC FUNCTION 1 : PROCESS PACKET/EVENT

 /***EP  VTEventProc - Process event packets from PDD.
  *
  *  ENTRY
  *      ulFunc == function code (VTDCMD_REPORT_EVENT)
  *      f16p1 -> MONREC
  *      f16p2 -  Not used.
  *
  *  EXIT
  *      None
  *
  *  USES
  *      32-bit small-model PASCAL calling/register conventions
  *
  *  CONTEXT
  *      Interrupt-time
  *
  *  PSEUDO-CODE
  *      if handle and pointer are valid and touch is enabled,
  *          add the event to the VDM's buffer.
  */
 VOID    VDDENTRY VTEventProc(ULONG ulFunc, F16PVOID f16p1, F16PVOID f16p2);

The MONREC pointer points to a structure as detailed below:

 /***ET+ PTD-to-VTD communication structures
  *
  */
 typedef struct {                                // VTDCMD_REPORT_EVENT
         USHORT          Status;
         ULONG           TimeStamp;
         USHORT          x;
         USHORT          y;
         USHORT          z;
     } QEVENT, * PQEVENT, * * PPQEVENT;
 typedef struct {
             USHORT      SGId;
             QEVENT      QEvent;
     } MONREC, * PMONREC;


VIRTUAL DEVICE DRIVER TO PHYSICAL DEVICE DRIVER

The primary function of this interface is to register the VDD with the PDD so that it can later call it back with data, establish the configuration set up (physical mouse attached or not, touch display calibrated or not etc.), and device control (emulation on/off, DOS property 'exclusive access' on/off etc.

The functions supported are:

  • Register VDD
  • Query configuration
  • Set emulation state
  • Disable
  • Set exclusive access

FUNCTION 0 : REGISTER VDD - PDDREGISTER

Establishes the VDD entry point for the PDD to call the VDD.

  /***LP  PddRegisterVdd - called when Vdd calls VDHOpenPDD()
   *
   * Input:
   *      USHORT  pIBuff.off      VDD's CS
   *      USHORT  pIBuff.sel      zero
   *      USHORT  pOBuff.off      low 16-bits of EIP for VDD entry point
   *      USHORT  pOBuff.sel      high 16-bits of EIP for VDD entry point
   *
   * Return:
   *      BOOL success (AX)
   *
   * Usage:
   *      Success = PddEntry( 0, VddEntrySelector, VddEntryOffset);
   *
   * Called from:
   *      PddEntry (seg3) via VdhOpenPdd()
   *
   */

  STATIC VDMFUNC PddRegisterVdd( PUSHORT pIBuff, PUSHORT pOBuff);

FUNCTION 1 : QUERY CONFIGURATION - PDDQUERYCONFIG

Returns device configuration information, including device interrupt request (IRQ) level, mouse status (physical mouse present, MOUSE.SYS driver attached and emulation state) and touch status (calibrated or not).

  /***LP  PddQueryConfig - copy device config data to a Vdd 16:16 ptr
   *
   * Input:
   *      None
   *
   * Return:
   *      Configuration data:
   *              USHORT  size = 7
   *              UCHAR   irq
   *              USHORT  mouse status
   *              USHORT  touch status
   *      BOOL success (AX)
   *
   * Usage:
   *      Success = PddEntry( 1, NULL, &ParmsAddr);
   *
   * Called from:
   *      PddEntry (seg3) [QueryType(&TouHardware)]
   */

  STATIC VDMFUNC PddQueryConfig( PUSHORT pOBuff);

FUNCTION 2 : SET EMULATION STATE - PDDSETEMUL

Used to switch mouse emulation in the DOS virtual machine off or on (relative/glass mouse or absolute).

  /***LP  PddSetEmul - set emulation state
   *
   * Input:
   *      Emulation data:
   *              USHORT  size = 3
   *              UCHAR   emul state (0 - off, 1 - absolute, 2 - glass)
   *
   * Return:
   *      BOOL success (AX)
   *
   * Usage:
   *      Success = PddEntry( 2, &DataAddr, NULL);
   *
   * Called from:
   *      PddEntry (seg3)
   */

  STATIC VDMFUNC PddSetEmul( PUSHORT pIBuff);

FUNCTION 3 : DISABLE - PDDDISABLE

  /***LP  PddDisable -
   *
   * Input:
   *      None
   *
   * Return:
   *      BOOL success (AX)
   *
   * Usage:
   *      Success = PddEntry( 3, NULL, NULL);
   *
   * Called from:
   *      PddEntry (seg3)
   */

  STATIC VDMFUNC PddDisable(VOID);

FUNCTION 4 : SET EXCLUSIVE ACCESS ON/OFF - PDDSETEXCLACC

Allows a DOS window to receive full screen touch data. (valid for the PM session only). Mouse emulation is effectively turned off when exclusive access in on.

  /***LP  PddSetExclAcc - set exclusive access on/off
   *
   * Input:
   *      Exclusive Access Data:
   *              USHORT  size = 3
   *              UCHAR   exclusive access flag (0 - off, 1 - on)
   *
   * Return:
   *      BOOL success (AX)
   *
   * Usage:
   *      Success = PddEntry( 4, &DataAddr, NULL);
   *
   * Called from:
   *      PddEntry (seg3)
   */

  STATIC VDMFUNC PddSetExclAcc( PUSHORT pIBuff);

Category 129 Touch Device Driver IOCtl Commands

All touch device driver IOCtl commands share Category 129, distinguished by the device name used in the device open (TOUCH$ for the device independent and PDITOU$ for the device dependent driver).

SUMMARY: DEVICE DEPENDENT DRIVER

Table 1. Category 129 PDITOU$ Device IOCtl Commands
50h Semaphore Get
51h Semaphore Release
52h Set Calibration Constants
53h Read Data
54h Set Mode
55h Set Click Locking Parameters
56h Set Thresholds
57h Set XY Offset
58h Set Report Rate
59h Set Low Pass Filter
5Ah Write Memory
5B - 5Fh Reserved
60H Get Calibration Constants
61H Get Data Mode
62H Get Click Lock Parameters
63H Get Touch Thresholds
64H Get Emulation XY Offset
65H Get Data Report Rate
66H Get Low Pass Filter
67H Read Memory Location
CATEGORY 129 - FUNCTION 50H - RESERVED
Currently performs no function
CATEGORY 129 - FUNCTION 51H - RESERVED
Currently performs no function
CATEGORY 129 - FUNCTION 52H - SET CALIBRATION CONSTANTS
Downloads the Touch Display Calibration constants

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Channel 1 gain constant      DWORD      |
|-----------------------------------------|
| Channel 2 gain constant      DWORD      |
|-----------------------------------------|
| Channel 3 gain constant      DWORD      |
|-----------------------------------------|
| Channel 4 gain constant      DWORD      |
|-----------------------------------------|
| X as a function of X  C[xx]  DWORD      |
|-----------------------------------------|
| X as a function of Y  C[xy]  DWORD      |
|-----------------------------------------|
| Y as a function of X  C[yx]  DWORD      |
|-----------------------------------------|
| Y as a function of Y  C[yy]  DWORD      |
|-----------------------------------------|
| X offset C[x0]               DWORD      |
|-----------------------------------------|
| Y offset C[y0]               DWORD      |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

        All parameters are in double word floating point
        format.  This format is non-IEEE standard and is
        described in the IBM Personal System/2 8516 Touch
        Display Technical Reference.

Returns

None

Remarks:

This function intended for exclusive use by the calibration utility.

CATEGORY 129 - FUNCTION 53H - READ DATA

Reads a single packet of data from the Touch Display controller. The format of the data, XYZ or Raw T1-4, depends on the data mode set using function 54H.

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage where the caller indicates action to be taken if no event queue data is available. The format of the parameter packet is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Read Type                    WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display device driver returns to the caller a touch display event queue record. This record has two formats, depending on the data type specified using function 54H. The two types of record are XYZ data or Raw data (the default setting will depend on which mode has been set using function 54H), see below:

XYZ data packet format

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Status                       WORD       |
|-----------------------------------------|
| Time                        DWORD       |
|-----------------------------------------|
| X value                      WORD       |
|-----------------------------------------|
| Y value                      WORD       |
|-----------------------------------------|
| Z value                      WORD       |
|-----------------------------------------|
| reserved                     WORD       |
*-----------------------------------------*

Raw data packet format

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Status                       WORD       |
|-----------------------------------------|
| Time                        DWORD       |
|-----------------------------------------|
| Transducer 1                 WORD       |
|-----------------------------------------|
| Transducer 2                 WORD       |
|-----------------------------------------|
| Transducer 3                 WORD       |
|-----------------------------------------|
| Transducer 4                 WORD       |
*-----------------------------------------*

Where

     Read type
       is used to determine the type of action taken if no
       event queue data is available.  The values may be:
         0 = Return NULL EventInfo if data not available
         1 = WAIT for data on empty queue.
         All other values reserved


     Status
       has the following bit level definitions for XYZ mode:
        Bit      Description
         0           1 = hardware offset adjust error
         1           1 = offset adjust error
         2           1 = floating point calculation error
         3           Reserved = 0
         4           1 = channel pegged error
         5           1 = offset adjust just occurred
         6           Reserved = 0
         7           Reserved = 0
         8           Reserved = 0
         9           Reserved = 0
         A           Reserved = 0
         B           Reserved = 0
         C           Touch screen status 2
         D           Touch screen status 1
         E           1 = selection detection on
         F           0 = XYZ packet
     Status
       has the following bit level definitions for RAW mode:
        Bit      Description
         1           Reserved = 0
         2           Reserved = 0
         3           Reserved = 0
         4           Reserved = 0
         5           Reserved = 0
         6           1 = channel pegged
         7           Reserved = 0
         8           Reserved = 0
         9           Reserved = 0
         A           1 = Adjust just occurred
         B           Reserved = 0
         C           Reserved = 0
         D           Reserved = 0
         E           1 = offset error
         F           1 = RAW data
         C           Touch screen status 2
         D           Touch screen status 1
         E           1 = selection detection on
         F           0 = XYZ packet
     Time
       is the timestamp in milliseconds
     X value
       is the touch contact x (horizontal) position
     Y value
       is the touch contact y (vertical) position
     Z value
       is proportional to the touch contact force
     Transducer n
       is the raw transducer output value.  Transducers are
       numbered clockwise from top left.

Returns

This function returns to the caller a touch event from the touch event (FIFO) queue flags.

Remarks:

CATEGORY 129 - FUNCTION 54H - SET DATA MODE

Set Data Mode - causes the touch display to report either XYZ type data or raw T1-T4 strain gauge data

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Mode                         DWORD      |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

      Mode
        Selects the relevant data packet reporting mode
         0 = XYZ mode
         1 = RAW mode
      see Function 53H for the data packet formats

Returns

None

Remarks:

RAW mode is intended for exclusive use by the calibration utility.

CATEGORY 129 - FUNCTION 55H - SET CLICK LOCK PARAMETERS

Specifies the Touch Display Click Lock Parameters

PARAMETER PACKET FORMAT

The data packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Active Area                  WORD       |
|-----------------------------------------|
| Timeout Period               WORD       |
|-----------------------------------------|
| Click Count                  BYTE       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     Active Area
        Specifies the X/Y pixel area that will cause a mouse emulation
        button 1 click (push harder threshold) to be held within a defined
        X/Y coordinate of first selection.
     Timeout Period
        Specifies the length of time in milliseconds that will cause a
        mouse emulation button 1 click to be held for, within a defined
        active area.
     Click Count
        Specifies the mouse emulation button 1 clicks that will be held
        within a defined area for a defined period of time.
        Value:
        0 = click locking off (default)
        1 = single button click locking
        2 = double button click locking
 Note:
 Any parameter value of '-1' will cause the driver default value to be
 substituted.

Returns

None

Remarks:

This function is particularly useful for manipulation of small areas using mouse emulation, for example moving Presentation Manager icons, etc. It is used by the Touch Control Panel utility.

CATEGORY 129 - FUNCTION 56H - SET TOUCH THRESHOLDS

Specifies the Touch Display Thresholds


PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| On Screen threshold          WORD       |
|-----------------------------------------|
| Push threshold               WORD       |
|-----------------------------------------|
| Push hysteresis threshold    WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     On Screen threshold
        sets the value of Z on the chosen Z scale at which the touch
        display will interpret the touch contact force as 'On screen' and
        start reporting data.  Data will only be reported while the force
        exceeds this threshold.
     Push threshold
        sets the value of Z, when Z is increasing, on the chosen Z scale
        at which the touch display will set the selection detection bit
        in the status returned by function 53H.
     Push hysteresis threshold
        sets the value of Z, when Z is decreasing, on the chosen Z scale
        at which the touch display will reset the selection detection bit
        in the status returned by function 53H.
 Note:
 Any parameter value of '-1' will cause the driver default value to be
 substituted.

Returns

None

Remarks:

Push and push hysteresis thresholds are only relevant when the selection detection mechanism of 'Push harder' is set (see function 52H of the device independent IOCTl's.

CATEGORY 129 - FUNCTION 57H - SET EMULATION XY OFFSET

Specifies the Touch Display XY Offset applied to touch data when passed as emulated mouse data.

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| X offset                     WORD       |
|-----------------------------------------|
| Y offset                     WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     X offset
        indicates the amount by which the X coordinate will be
        offset.
     Y offset
        indicates the amount by which the Y coordinate will be
        offset.

Returns

None

Remarks:

Calls to the mouse device independent driver via the IDC will have the x and y coordinate offsets applied to the touch x,y,z data. Data supplied to the touch device independent driver is not affected.

CATEGORY 129 - FUNCTION 58H - SET DATA REPORT RATE

Specifies the Touch Display Data Report Rate

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Report rate                  WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     Report rate
        sets the maximum rate at which data packets will be
        returned by the touch display while the touch contact force
        exceeds the On Screen threshold (see function 56H).
        Value:
        0 = 10 reports per second
        1 = 20 reports per second
        2 = 30 reports per second
        3 = 40 reports per second
        4 = 60 reports per second
        -1 = driver default value
        All other values reserved.

Returns

None

Remarks:

CATEGORY 129 - FUNCTION 59H - SET LOW PASS FILTER

Specifies the Touch Display Low Pass Filter Parameters

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Filter type                  USHORT     |
|-----------------------------------------|
| Filter frequency             USHORT     |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     Filter type
       Determines the type of low pass filter to be used
       Value:
       0 = Default (Touch Display)
       1 = Alternative (Touch Panel)
       All other values reserved


     Filter frequency
       Determines the frequency cut off value for the filter
       Value:
       0 = Default (Medium)
       1 = Slow
       2 = Medium
       3 = Fast
       4 = Rapid
       All other values reserved

Returns

None.

Remarks:

This function is used by the Touch Control Panel.

CATEGORY 129 - FUNCTION 5AH - WRITE MEMORY LOCATION

Write a byte to Touch Display controller RAM

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Data to write                BYTE       |
|-----------------------------------------|
| Address to write at          WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Returns

None

Remarks:

CATEGORY 129 - FUNCTION 5B - 5FH - RESERVED
CATEGORY 129 - FUNCTION 60H - GET CALIBRATION CONSTANTS

Gets the Touch Display Calibration constants

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the Touch Display Device driver will return the current set of calibration constants. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Channel 1 gain constant      DWORD      |
|-----------------------------------------|
| Channel 2 gain constant      DWORD      |
|-----------------------------------------|
| Channel 3 gain constant      DWORD      |
|-----------------------------------------|
| Channel 4 gain constant      DWORD      |
|-----------------------------------------|
| X as a function of X  C[xx]  DWORD      |
|-----------------------------------------|
| X as a function of Y  C[xy]  DWORD      |
|-----------------------------------------|
| Y as a function of X  C[yx]  DWORD      |
|-----------------------------------------|
| Y as a function of Y  C[yy]  DWORD      |
|-----------------------------------------|
| X offset C[x0]               DWORD      |
|-----------------------------------------|
| Y offset C[y0]               DWORD      |
*-----------------------------------------*

Where

        All parameters are in double word floating point
        format.  This format is non-IEEE standard and is
        described in the IBM Personal System/2 8516 Touch
        Display Technical Reference.

Returns

None

Remarks:

This function intended for exclusive use by the calibration utility

CATEGORY 129 - FUNCTION 61H - GET DATA MODE

Gets the Current Touch Display data packet reporting mode

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the current data packet reporting mode The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Mode                         WORD       |
*-----------------------------------------*

Where

      Mode
        Indicates the current data packet reporting mode
         0 = XYZ mode
         1 = RAW mode
      see Function 53H for the data packet formats

Returns

This function returns to the caller Current Touch Display data packet reporting mode.

CATEGORY 129 - FUNCTION 62H - GET CLICK LOCK PARAMETERS

Gets the Touch Display Click Lock Parameters

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display device driver returns to the caller the current click locking settings. The format is as follows:


*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Active Area                  WORD       |
|-----------------------------------------|
| Timeout Period               WORD       |
|-----------------------------------------|
| Click Count                  WORD       |
*-----------------------------------------*

Where

     Active Area
        Specifies the X/Y pixel area that will cause a mouse emulation
        button 1 click (push harder threshold) to be held within a defined
        X/Y coordinate of first selection.
     Timeout Period
        Specifies the length of time in milliseconds that will cause a
        mouse emulation button 1 click to be held for, within a defined
        active area.
     Click Count
        Specifies the mouse emulation button 1 clicks that will be held
        within a defined area for a defined period of time.
        Value:
        0 = click locking off (default)
        1 = single button click locking
        2 = double button click locking

Returns

This function returns to the caller the mouse emulation click locking settings.

Remarks:

This function is particularly useful for manipulation of small areas using mouse emulation, for example moving Presentation Manager icons, etc.

The tendency of the emulated mouse position to change while attempting to button click can be eliminated with only a small initial 'hesitation' noted as a side affect while attempting to drag the cursor.

A setting of 3-500 ms for the timeout period is recommended, while the active area setting will depend on the screen pixel resolution: as a guide use a value approximately equal to half the size of an icon.

CATEGORY 129 - FUNCTION 63H - GET TOUCH THRESHOLDS

Gets the Current Touch Display Thresholds

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the current touch display threshold settings. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| On Screen threshold          WORD       |
|-----------------------------------------|
| Push threshold               WORD       |
|-----------------------------------------|
| Push hysteresis threshold    WORD       |
*-----------------------------------------*

Where

     On Screen threshold
        is the value of Z on the chosen Z scale at which the touch
        display will interpret the touch contact force as 'On screen' and
        start reporting data.  Data will only be reported while the force
        exceeds this threshold.
     Push threshold
        is the value of Z, when Z is increasing, on the chosen Z scale at
        which the touch display will set the selection detection bit in
        the status returned by function 53H.
     Push hysteresis threshold
        is the value of Z, when Z is decreasing, on the chosen Z scale at
        which the touch display will reset the selection detection bit in
        the status returned by function 53H.

Returns

This function returns to the caller the current threshold values.

Remarks:

Push and push hysteresis thresholds are only relevant when the selection detection mechanism of 'Push harder' is set (see device independent IOCTls function 52H).

CATEGORY 129 - FUNCTION 64H - GET EMULATION XY OFFSET

Gets the Touch Display XY Offsets applied during mouse emulation.

PARAMETER PACKET FORMAT

None


DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the values of the x and y offsets which are added to the basic x,y data before being supplied to the mouse device independent driver via its absolute IDC entry point. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| X offset                     WORD       |
|-----------------------------------------|
| Y offset                     WORD       |
*-----------------------------------------*

Where

     X offset
       indicates the amount by which the X coordinate will be offset.
     Y offset
       indicates the amount by which the Y coordinate will be offset.

Returns

This function returns to the caller the current X and Y coordinate offsets applied during mouse emulation.

Remarks:

This function is used by the Touch Control Panel and is used in order to offset the mouse pointer image from the finger, to enable the image to be seen while touching the screen.

CATEGORY 129 - FUNCTION 65H - GET DATA REPORT RATE

Gets the Current Touch Display data packet report rate.

PARAMETER PACKET FORMAT

None


DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the touch display maximum data reporting rate. The format is as follows:


*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Report rate                  WORD       |
*-----------------------------------------*

Where

     Report rate
        is the maximum rate at which data packets will be returned
        by the touch display while the touch contact force exceeds
        the On Screen threshold (see function 56H).
        Value:
        0 = 10 reports per second
        1 = 20 reports per second
        2 = 30 reports per second
        3 = 40 reports per second
        4 = 60 reports per second
        All other values reserved.

Returns

This function returns to the caller the data report rate.

Remarks:

The actual reporting rate may vary up to the maximum quoted rate.

CATEGORY 129 - FUNCTION 66H - GET LOW PASS FILTER

Gets the Current Touch Display Low Pass Filter Parameters

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the low pass filter settings. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Filter type                  USHORT     |
|-----------------------------------------|
| Filter frequency             USHORT     |
*-----------------------------------------*

Where

     Filter type
       Indicates the type of low pass filter being used
       Value:
       0 = Default (Touch Display)
       1 = Alternative (Touch Panel)
       All other values reserved


     Filter frequency
       Indicates the frequency cut off value for the filter
       Value:
       0 = Default (Medium)
       1 = Slow
       2 = Medium
       3 = Fast
       4 = Rapid
       All other values reserved

Returns

This function returns to the caller the low pass filter settings.

Remarks:

A single set of filter constants set in one screen group apply screen group wide. The Touch Control Panel makes use of this function.

CATEGORY 129 - FUNCTION 67H - READ MEMORY LOCATION

Reads a byte from Touch Display controller RAM

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Data read from RAM           BYTE       |
|-----------------------------------------|
| Address to read from         WORD       |
*-----------------------------------------*

Returns

None

Remarks:

SUMMARY
DEVICE INDEPENDENT DRIVER
Table 2. Category 129 TOUCH$ Device IOCtl Commands
50h Set Coordinate System
51h Reserved
52h Set Selection Mechanism
53h Set Event Mask
54h Set Queue Size
55h Set Emulation State
60h Get Coordinate System
61h Get Coordinate Origin
62h Get Selection Mechanism
63h Get Event Mask
64h Get Queue Size
65h Get Emulation State
66h Read Event Queue
CATEGORY 129 - FUNCTION 50H

Specifies the Touch Display coordinate system


PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| X min                        WORD       |
|-----------------------------------------|
| X max                        WORD       |
|-----------------------------------------|
| Y min                        WORD       |
|-----------------------------------------|
| Y max                        WORD       |
|-----------------------------------------|
| Z min                        WORD       |
|-----------------------------------------|
| Z max                        WORD       |
|-----------------------------------------|
| X hysteresis                 WORD       |
|-----------------------------------------|
| X hysteresis                 WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     X min
        is the value of x to be reported at the left hand edge of
        the display.
     X max
        is the value of x to be reported at the right hand edge of
        the display.
     Y min
        is the value of y to be reported at the top edge of the
        display.
     Y max
        is the value of y to be reported at the bottom edge of the
        display.
     Z min
        is the notional value that would be reported with minimum
        contact force applied.  This is because Z values are only
        reported when they exceed the On Screen threshold.
        Values from Z min to On Screen threshold will never be reported.
     Z max
        is the value to be reported with maximum contact force applied
     X hysteresis
        is the amount of hysteresis in the horizontal direction in
        cell units multiplied by 1000.  Eg hysteresis of 0.4 will
        return 400.
     Y hysteresis
        is the amount of hysteresis in the horizontal direction in
        cell units multiplied by 1000.  Eg hysteresis of 0.4 will
        return 400.

Returns

None

Remarks:

X, and Y values are treated as 16 bit 2's complement signed integers in the range -32768 to 32767.

Hysteresis values are unsigned integers in the range 0 - 65535.

Hysteresis values required should be expressed in terms of the hysteresis value, in X,Y coordinate system units, multiplied by 1000.

CATEGORY 129 - FUNCTION 51H

Performs no function: reserved

CATEGORY 129 - FUNCTION 52H

Specifies the Touch Display Selection Mechanism method

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Type                         WORD       |
|-----------------------------------------|
| Number of stable points      WORD       |
|-----------------------------------------|
| Tolerance value              WORD       |
|-----------------------------------------|
| Stable region length         WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     Type
        the in which the selection detection flag (bit)
        in the status word returned in function 66H is set/reset
        Bit 0
          0 = Push harder (default)
          1 = Lift off
        Bit 1
          0 = First value taken
          1 = Single touch algorithm applied
        Bit 2
          0 = First value taken
          1 = Stable region algorithm active
        Bit 3-F
          0 = Reserved


     Number of stable points
        Value:
           0 = default
           n = # of stable points
     Tolerance value
           0 = default
           n = tolerance in pixels
     Stable region length
           0 = default
           n = region length in samples ( 0 < n < 60 )

Returns

None

Remarks:

For information on the single touch and stable region algorithms, see under -- Heading 'BISTAL' unknown --.

CATEGORY 129 - FUNCTION 53H

Assigns a new Touch Display Event Mask

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Event Mask                   WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

Event mask

Bit      Meaning

0         1 = On Screen status set event
1         1 = Touch Down event (On Screen status clear to set)
2         1 = Lift Off event (On Screen status set to clear)
3         1 = Selection Detection flag set event
4         1 = Selection Detection flag clear to set event
5         1 = Selection Detection flag set to clear event
6-F       Reserved = 0

Returns

None

Remarks:

The touch display device driver gets the new mask for enabled/disabled touch display device events from the caller's parameter packet. The mask determines which events are to be queued, that is readable by calling Category 129, Function 66H.


CATEGORY 129 - FUNCTION 54H

Sets the Touch Display event queue size.

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Queue Size                   WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     Queue Size
       indicates how many touch display events into the past
       will be stored in the event queue.

Returns

None

Remarks:

The queue size set may be any value from 1 to a maximum of the QSIZE parameter specified in the device driver CONFIG.SYS statement (which defaults to 10 if not specified).

CATEGORY 129 - FUNCTION 55H

Specifies the Touch Display mouse emulation state: on or off.

PARAMETER PACKET FORMAT

The parameter packet is a location in application storage that contains the following data:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Emul state                   WORD       |
*-----------------------------------------*

DATA PACKET FORMAT

None

Where

     Emul state
       switch which turns mouse emulation on or off for the screen
       group.
        Bit      Description
         0       Screen group emulation
                 =0 = Emulation off, =1 = Emulation on
         1-F     Reserved

Returns

None

Remarks:

Calls the device dependent driver via the IDC to set/reset the emulation state.

Using this function, emulation can be turned on after the touch device is opened (the act of which disables emulation temporarily), assuming that emulation is available with EMUL= 1 specified in the touch display TOUCH.INI configuration file.

CATEGORY 129 - FUNCTION 60H

Gets the Touch Display coordinate system

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the coordinate system being used to report X,Y,Z data report values, including maximum and minimum limits and change report hysteresis values. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| X min                        WORD       |
|-----------------------------------------|
| X max                        WORD       |
|-----------------------------------------|
| Y min                        WORD       |
|-----------------------------------------|
| Y max                        WORD       |
|-----------------------------------------|
| Z min                        WORD       |
|-----------------------------------------|
| Z max                        WORD       |
|-----------------------------------------|
| X hysteresis                 WORD       |
|-----------------------------------------|
| X hysteresis                 WORD       |
*-----------------------------------------*

Where

     X min
        is the value of x to be reported at the left hand edge of
        the display.
     X max
        is the value of x to be reported at the right hand edge of
        the display.
     Y min
        is the value of y to be reported at the top edge of the
        display.
     Y max
        is the value of y to be reported at the bottom edge of the
        display.
     Z min
        is the notional value that would be reported with minimum
        contact force applied.  This is because Z values are only
        reported when they exceed the On Screen threshold.
        Values from Z min to On Screen threshold will never be reported.
     Z max
        is the value to be reported with maximum contact force applied
     X hysteresis
        is the amount of hysteresis in the horizontal direction in
        cell units multiplied by 1000.  Eg hysteresis of 0.4 will
        return 400.
     Y hysteresis
        is the amount of hysteresis in the horizontal direction in
        cell units multiplied by 1000.  Eg hysteresis of 0.4 will
        return 400.

Returns

This function returns to the caller the current X,Y,Z coordinate reporting range and the X,Y coordinate change hysteresis values.

Remarks:

X, and Y values are 16 bit 2's complement signed integers in the range -32768 to 32767.

Hysteresis values are unsigned integers in the range 0 - 65535.

Hysteresis values are expressed in terms of the hysteresis value, in X,Y coordinate system units, multiplied by 1000.

CATEGORY 129 - FUNCTION 61H

Performs no function: reserved.

CATEGORY 129 - FUNCTION 62H

Gets Touch Display Selection Mechanism method

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the touch display selection mechanism method. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Type                         WORD       |
|-----------------------------------------|
| Number of stable points      WORD       |
|-----------------------------------------|
| Tolerance value              WORD       |
|-----------------------------------------|
| Stable region length         WORD       |
*-----------------------------------------*

Where

     Type
        the in which the selection detection flag (bit)
        in the status word returned in function 66H is set/reset
        Bit 0
          0 = Push harder (default)
          1 = Lift off
        Bit 1
          0 = First value taken
          1 = Single touch algorithm applied
        Bit 2
          0 = First value taken
          1 = Stable region algorithm active
        Bit 3-F
          0 = Reserved


     Number of stable points
        Value:
           0 = default
           n = # of stable points
     Tolerance value
           0 = default
           n = tolerance in pixels
     Stable region length
           0 = default
           n = region length in samples ( 0 < n < 60 )

Returns

None

Remarks:

For information on the single touch and stable region algorithms, see under -- Heading 'BISTAL' unknown --.

CATEGORY 129 - FUNCTION 63H

Gets the current Touch Display Event Mask

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the touch display event mask, which controls ('masks') which type of events are to added to the the event queue. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Event Mask                   WORD       |
*-----------------------------------------*

Where

     Event mask
     Bit      Meaning
      0         1 = On Screen status set event
      1         1 = Touch Down event (On Screen status clear to set)
      2         1 = Lift Off event (On Screen status set to clear)
      3         1 = Selection Detection flag set event
      4         1 = Selection Detection flag clear to set event
      5         1 = Selection Detection flag set to clear event
      6-F       Reserved = 0

Returns

None

Remarks:

CATEGORY 129 - FUNCTION 64H

Gets the current Touch Display event queue size.

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the size of the touch display event queue. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Queue Size                   WORD       |
*-----------------------------------------*

Where

     Queue Size
       indicates how many touch display events into the past
       are being stored in the event queue.

Returns

None

Remarks:

CATEGORY 129 - FUNCTION 65H

Gets the current Touch Display mouse emulation state.

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the touch display mouse emulation state The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| Emul State                   WORD       |
*-----------------------------------------*

Where

     Emul state
       switch which turns mouse emulation on or off for the screen
       group.
        Bit      Description
         0       Screen group emulation
                 =0 = Emulation off, =1 = Emulation on
         1-F     Reserved

Returns

None

Remarks:

Calls the device dependent driver via the IDC to get the emulation state.

CATEGORY 129 - FUNCTION 66H

Reads an event from the Touch Display event queue

PARAMETER PACKET FORMAT

None

DATA PACKET FORMAT

The data packet is a location in application storage where the touch display driver will return to the caller the touch display event. The format is as follows:

*-----------------------------------------*
| Field                        Length     |
|-----------------------------------------|
| remaining events             WORD       |
|-----------------------------------------|
| status                       WORD       |
|-----------------------------------------|
| timestamp                    WORD       |
|-----------------------------------------|
| x                            WORD       |
|-----------------------------------------|
| y                            WORD       |
|-----------------------------------------|
| z                            WORD       |
*-----------------------------------------*


Where

     remaining events
       count of the number of events remaining in the queue besides
       this current event.  Less than or equal to queue size less one.
     status
       status bits pertaining to this touch display event.
     timestamp
       relative time at which event occurred in milliseconds.
     x
       horizontal coordinate value of touch event
     y
       vertical coordinate value of touch event
     z
       third dimension coordinate value of touch event


Returns

None

Remarks:

Bit definitions of the event status are identical to those of the event mask (see also IOCtl's 53H and 63H).

Events are placed in the event queue which have at least one status bit in common with the current event mask. For instance, if the event mask has bits 1,2 and 3 set, only events which have either the status bit for Touch Down (bit 1), Lift Off (bit 2) or Selection Detection (bit3) set (or any combination thereof) will be placed in the event queue to be read by this function.

For IBM PS/2 8516 Touch Display, the z value is proportional to the force applied.

The 'Remaining events returned' value gives this function the equivalent capability as a 'Get Number of Queue Elements' type function, except that with one function call the number of remaining events is not subject to any uncertainty that would arise with two separate calls (one to read the data, the other to read how many events remained) where events could arrive in between making the calls.

Virtual Touch Driver Architecture

OBJECTIVES

Applications that support IBM PS/2 8516 Touch Display in the DOS environment shall do so via the INT7Fh API described below. Applications that use INT15h AH=C2h AL=10h to AL=26h BIOS calls or those that talk directly to the 8042 device hardware will not be supported.

INT 7FH SUPPORT

This will be provided directly by the Virtual Touch Driver (VTD), using a standard VDM software interrupt hook. This support is essentially the same as that provided in OS/2 1.2/3 versions of the Device Independent Touch Driver, but is re-written to run in protected mode, which allows it to share code in all VDM's, as well as virtualising all the hardware dependent features that the INT7Fh interface provides (changing thresholds etc.).

Note, however, that only DOS sessions running full screen can obtain full touch XYZ data, windowed DOS sessions running under PM being restricted to emulated mouse data. A DOS touch application which is started as full screen will stop receiving touch data if it is switched to a window, and then start receiving data again if it switched back to full screen. Conversely, a DOS touch application which is started in a window, will not receive data until it is switched to full screen, and so on.

This is the default mode of operation: for those applications that insist on being able to access full touch x,y,z data in a DOS window, the DOS property 'Touch: exclusive to a window' can be turned on. This effectively turns mouse emulation off, and gives all the touch x,y,z data directly to a window.

INT7FH SOFTWARE INTERRUPT AND FUNCTION TABLE CALL HANDLING

Following is the sequence of events when a real mode program issues a software interrupt that has been hooked by a VDD:

  • At create time, VDD installs interrupt vector hook (InstallHookVect())
  • Interrupt vector table gets patched with address A
  • Address A points to an illegal real mode instruction (ARPL)
  • Software interrupt causes transfer to address A
  • Execution of the ARPL located there instruction causes a trap
  • OS/2 fields this trap
  • ??? OS/2 looks into a list of procs that are registered for this trap via InstallHookVect and calls each one in turn
  • Hook procs get passed pointer to Client Register Frame
  • Hook procs process call based on registers passed in CRF
  • If Hook procs int then does VDHPopInt() (fills return CS:IP in CRF)
  • Hook procs returns TRUE if its int else FALSE
  • ??? OS/2 calls next in chain if FALSE else returns to CS:IP as filled in in CRF.

With IBM PS/2 8516 Touch Display, the interface to device driver is via a call table, the address of which the application obtains by issuing INT7F with AX=ABCDh and BX=0h. Once it has obtained the call table address (CTA), it then calls the individual function it requires by calling the address at (CTA) + 4*(FN-1) where FN is the required device driver function number.

This cannot be done in the above scheme, as calls cannot be made directly from the real mode app to the protected mode VDD.

The mouse INT33 driver has a related problem, in that it has a BASIC entry point located 2 bytes forward from the actual INT33 vector address (first instruction of the INT33 handler is a jump over the BASIC entry point code). A BASIC application would therefore obtain address A and then call (address A + 2) which could be anything.

To resolve this, the VDD has to have a real mode portion which has a software interrupt handler similar to that provided by the real DOS driver. The address A is then replaced by the address of this handler (address B) by the VDD at create time, as well as saving Address A in the real mode portion.

For the particular case of the IBM PS/2 8516 Touch Display driver, the call table must also be part of the real mode portion, enabling calls to its entries to be made directly by real mode apps, with the interrupt handler setting the address of the table in ES:BX as in the real DOS driver, before calling address A. If the handler received a call which did not belong to it (AX !=ABCDh) then it would call address A directly.

The entries in the call table then consists of a common call into a 'router'. The router would determine the function number from the address from which it was called, and then set up the registers appropriately before calling address A.

             REAL                         PROTECTED
                              |
              Interrupt       |
              vector table    | *->ARPL-->OS2-*
                              | |  *------<---*          Hook proc 1
             *-----------*  *---* *V---------*   *---->*-----------*
             |           |  | |   | ------- -+---* <*  |           |
             |           |  | |   | ------- -+---*  |  |           |
             |           |  | |   |    .     |<* |  |  |           |
             |           |  | |   |    .     | | |  |  |           |
             |           |  | |   | -------  | | |  |  |           |
             |           |  | |   *----------* | |  |  |           |
             |-----------|  | |                | |  |  |           |
  INT 7F -- *< address B |  | |    list of     | |  |  |           |
            ||-----------|  | |    Installed   | |  *-<*-----------*
            ||           |  | |    IntHook's   | |
            |*-----------*  | |                | |       Hook proc 2
            |               | |                | *---->*-----------*
            V               A |                |       |           |
            |               | |                |       |           |
  Router -->|*-----------*  | |                |       |           |
            ||-----------|  | |                |       |           |
            || address A |->| |                |       |           |
            ||-----------|  | |                |       |           |
            ||           |<*| |                |       |           |
  Int 7F -->||-----------| || |                |       |           |
  handler   *>           | || |                *---<---*-----------*
             |           | || |
             |           | || |
             |        ->-+-+* |
  Int 7F     |-----------| |  |
  jump       |  ------- -+-*  |
  table      |  -------  |    |
             |  -------  |    |
             |     .     |    |
             |     .     |    |
             |     .     |    |
             |  -------  |    |
             *-----------*    |
                              |

Figure 4. Software interrupt and INT7F call table. route from real mode app to protected mode VDD handler

PTD - VTD INTERFACE

This interface is very similar to the PMD - VMD interface, except that is passes absolute touch x,y,z,status data information instead of mouse row,col,status data.

The PTD is aware at all times which session owns the touch device: when this is a foreground VDM, it notifies the VTD of the touch events. These are then immediately buffered in the VTD. The VTD then processes the event by updating the INT7Fh data structures for the foreground VDM, as well as handling the touch event user subroutine if one is registered (see below).

Note that the specific case of the Presentation Manager session is handled differently in the case of the mouse, where the event is sent to the PM single queue by the PMD, whence PM notifies the VMD whenever the mouse pointer is over a windowed VDM (and also performs coordinate conversion on behalf of the windowed VDM). Note also if an alternate mouse coordinate system is set up in the VDM, the VMD must discard any events posted by PM that fall outside the coordinate system but are otherwise within the VDM window.

Prescott and its VTD does not have any such relationship set up between itself and PM (nor is there any architected mechanism for it to do so, as the single queue only supports keyboard and mouse events). This is one problem that prevents the VTD from providing full touch data for windowed VDM's (or indeed for supporting the TdiXXX API properly for VIO windows). When a touch event is received while in the PM session, the PTD can only handle the event as though it were a normal full screen OS/2 session: in other words the event passes through the device monitor chain before being buffered in a PTD queue. This is because the PTD has no information regarding the arrangement of the PM desktop, location and size of windowed DOS sessions etc. to allow it to directly inform the VTD of the event (correctly tagged with the target VDM handle and coordinate converted).

EVENT NOTIFICATION

Each time the VTD is notified of a touch event, it may have to notify a VDM user subroutine. This will depend on (a) whether the VDM has a user subroutine registered via INT7Fh and (b) whether the call mask conditions match the event.

The calling of the user subroutine is done by simulating an interrupt into the VDM. An interrupt service routine (in the VTD) is loaded into each VDM at create time. This routine services the interrupt (PopInt, ClearIRR, issues SendVEOI, PushRegs), then sets up a Client Register Frame containing the appropriate values of the registers and then performs a VDHPushFarCall to the user subroutine. It also arms a return hook procedure to get control after the user subroutine has completed. When the context of the VDM next becomes current, it executes the user subroutine, and when the return hook procedure gets control back it just does a PopRegs.

The interrupt number chosen for simulation is the hardware interrupt being used by the PTD. For IBM PS/2 8516 Touch Display, this will be IRQ12, the same as the PS/2 mouse, unless we make it different (the problem is then deciding on what interrupt number can be used, without stepping on the toes of some other VDD).

Q. will the virtual PIC be able to handle interrupt simulations on the same interrupt (74H) separately for the VMD and VTD?

A. yes, but it requires that IRQ12h/INT74h is handled as a shared interrupt in the virtual device drivers which simulate and service this interrupt.

So IBM PS/2 8516 Touch Display and the PS/2 mouse can simulate and service their own interrupts separately while using the same IRQ12h/INT74h.

Algorithms to improve touch selection

In addition to the straightforward method for setting the selection detection flag on push harder or lift off, where the 'snapshot' x,y value when crossing a given z threshold is used directly, further processing of the x,y,z data packets can be brought into play to enhance the repeatability and accuracy of the x,y report.

(these improved methods of selection detection were introduced from DOS driver level 0.9q onwards).

The data processing algorithms are:

  1. Single touch algorithm
  2. Stable region algorithm (also called 'Back in the stack' algorithm)

Acknowledgement:

             REAL                         PROTECTED
                              |
              Interrupt       |
              vector table    | *->ARPL-->OS2-*
                              | |  *------<---*          Hook proc 1
             *-----------*  *---* *V---------*   *---->*-----------*
             |           |  | |   | ------- -+---* <*  |           |
             |           |  | |   | ------- -+---*  |  |           |
             |           |  | |   |    .     |<* |  |  |           |
             |           |  | |   |    .     | | |  |  |           |
             |           |  | |   | -------  | | |  |  |           |
             |           |  | |   *----------* | |  |  |           |
             |-----------|  | |                | |  |  |           |
  INT 7F --> | address A |--* |    list of     | |  |  |           |
             |-----------|    |    Installed   | |  *--*-----------*
             |           |    |    IntHook's   | |
             *-----------*    |                | |       Hook proc 2
                              |                | *---->*-----------*
                              |                |       |           |
                              |                |       |           |
                              |                |       |           |
                              |                |       |           |
                              |                |       |           |
                              |                |       |           |
                              |                |       |           |
                              |                |       |           |
                              |                *-------*-----------*

Figure 3. Software interrupt handling: Route from real mode app to protected mode VDD handler

These algorithms were developed at the IBM Thomas J. Watson Research Center by Jim Levine (LEVINE2 at YKTVMZ) and it is hoped that these implementations remain faithful to the original.

The algorithms are activated by setting the appropriate bit in the selection detection mechanism type parameter of Function 6 'Set Selection Mechanism'. Only one algorithm can be active at any given time, in either Push Harder or Lift Off mode.

3. 'Click locking'

Click locking was introduced primarily as a means by which the OS/2 Presentation Manager could more successfully be operated in mouse emulation mode, but was found to be equally as useful in the DOS environment.

ACCURACY OF THE X,Y REPORT

Touch accuracy (or lack thereof) is one of the main contributing reasons to the need to improve touch selection.

There are many factors which can affect touch (in)accuracy. These include:

  • Style of touch
As the screen is being touched, from the point of touch down to lift off, there may be some appreciable movement of the reported x,y position even if the intention is to keep the point of contact stationary. This can be dependent on the manner the screen is touched, where a rapid 'stab' at the screen can produce a larger variation than a slower, lighter touch.
  • On screen touch threshold
Lowering the on screen touch threshold makes the system not only more sensitive to a touch, but also to external unwanted 'noise' such as mechanical vibration.
  • Filter cut off frequency
Increasing the system's low pass cut off frequency may increase the system's responsiveness to fast touches, but does so at the expense of being able to filter out unwanted noise/variation/movement.

SINGLE TOUCH ALGORITHM

BENEFITS

The single touch algorithm is primarily designed to offer more consistent 'touch-down' x,y coordinates over a wide range of applied touch speed and pressure.

The single touch algorithm prevents the 'snapshot' x,y data taken at the first point of contact being used when the following data reports are moving rapidly away from the initial position (for example, because the screen has been 'poked' giving initial inaccurate data reports). Rather, it ensures the the data reports have settled down within a consistent area for a given number of reports (the size of the area and number of reports are determined by additional (optional) parameters).

The algorithm simply check each point with its succeeding neighbour, and if the second differs from the first by an amount which is within the defined tolerance, a count is incremented. If not, the count is set to zero. Only when the count has reached the defined minimum is the data deemed to have settled and the x,y report given with the status of 'selection detected'.

In the push harder mode, it is possible to touch the screen and lift off within having satisfied the condition and generated the 'selection detected'. In the lift off mode

The algorithm does have the drawback that as the number of reports and tolerance parameters are tightened, so is the requirement for more controlled, slow and deliberate touches. Lightly tapping or quickly stabbing the screen are less likely to trigger the algorithm either because of lack of sufficient data or too much variation within the data.

Because of this, it is less likely to be of use in an untrained user/public kiosk type environment where user frustration would probably result. In any event, applications designed to be used in such environments would generally avoid the effect of inaccuracy/repeatability by having more simply designed screens with large, widely spaced targets.

PSEUDOCODE

          If status == on-screen
             Call Update single touch x,y
             If selection method == Lift Off
                Return()
             Else   /* must be push harder */
                If !(sm detected flag)
                   Return()
                Else
                   If single touch sent
                      Return()           /* only send once on transition */
                   Else                  /* this is the first time       */
                                         /* select detect has gone on    */
                      current x,y = single touch x,y
                      single touch sent = TRUE
                      Return()
                   Endif
                Endif
             Endif
          Else
             If status == touch down
                single touch x,y = current x,y
                sm detected flag = single touch sent = FALSE
                count = RESET_VALUE
                Return()
             Else
                If (selection method == Lift Off) && (status == lift-off)
                   Call Update_Single_Touch_xy()
                   current x,y = single touch x,y
                   Return()
                Endif
             Endif
          Endif


          Procedure Update_Single_Touch_xy()
             If Modulus( Current x,y - single touch x,y ) < tolerance
                Single Touch x,y = (Single Touch x,y + Current x,y ) / 2
                count--
                If (count==0) set sm detect flag
             Else
                Single Touch x,y = current x,y
                count = RESET_VALUE
             Endif
          Endproc

'BACK IN THE STACK' ALGORITHM

BENEFITS

The 'Back in the Stack' (BIST) algorithm provides for detailed selection of an item (down to pixel level at 640 x 480 resolution) even in the presence of varying x,y data packets when the selection needs to be made.

For example, it may be relatively easy to adjust the touch contact so that the required (small) item is identified, but then much more difficult to actually perform the selection, either by lifting off or pressing harder, without involuntarily moving the x,y position and thereby selecting the wrong item.

The BIST algorithm gets round this by exploiting the natural way in which such a selection would be made: usually the touch contact position is adjusted until the required item is identified, hold momentarily, then the selection gesture made.

Thus, instead of taking the snapshot x,y position at the time the gesture is recognised (the z value exceeds the push harder threshold, or a lift off event status is reported), 'looks back' into a circular buffer (a form of stack containing the N most recent x,y,z reports, where the oldest contents are continually being overwritten by the newest) to find the plateau region where the touch was held on the required item.

Having found a plateau region of sufficient length, the x,y values of the data report containing the 'selection detected' status are taken from the average of the x,y values of the reports in the stable region.

In this way, the x,y value reported is relatively immune to any variations in x,y which take place between finding the item, and then trying to select it.

The following figure illustrates the technique:

    |   *
 C  |    **       *
 o  |      *       *    *           *
 o  |      *     *  **** ***** * *** *
 r  |        *  *             * *     *
 d  |          *                       *
 i  |         *                         *
 n  |                                    * *
 a  |                                       *
 t  |                                        *
 e  |                                         *  <--- Lift off
    |
    *-------------------------------------------------------------

        |          |                |                         Time ->
         Manipulation   Hold on item  Select item by
         to identify    to select     lift off
         item

igure 5. Back in the Stack algorithm. Finding the selection plateau region

Note the typical way in which the x,y position tends to 'slide' away from the required selection point (and therefore make selection of the required item impossible by normal means) as the selection gesture is made by releasing the touch force.

Without the BIST algorithm, the smallest size of selection item would be restricted to approximately twice the anticipated x,y movement from selection to lift off.

What the BIST algorithm provides, therefore, is the ability to track back through a short history of the data to determine that a selection point was being held just prior to lift off. In this way, the selection item size is limited by the amount of x,y jitter while a touch is being held steady.

An alternative use for the BIST algorithm is to provide a means for cancelling a selection when it would otherwise be inevitable: this is the case where the selection method is lift off, and there is no 'dead area' on the screen for the user to move to and lift off without selecting anything. Wherever the user decides to lift off, they will select something. What, then, do they do if they touch the screen by accident, or touch and then decide to cancel the operation?

In either case, all the user has to do is to lift off in a long, exaggerated 'swiping' motion. What this does is to fill up the stack/circular buffer with continuously varying data so that there is no plateau region for the algorithm to find.

Detailed selection in the manner described, and/or the method of 'not-selecting' would, of course, be restricted to experienced users as both are operations which require a small degree of practice, and in the case of the ability to 'not-select', knowledge that the facility existed at all (since a full screen select sensitive application screen would presumably leave no room for help instructions...).

PSEUDOCODE

Main routine

          If status == on-screen
             put x,y into circular buffer
             If selection method == Lift Off
                Return()
             Else     /* must be push harder */
                If ( z < Push Harder Threshold )
                   Return()
                Else
                   Call Send_Stable_Data
                Endif
             Endif
          Else
             If status == touch-down
                flush circular buffer
                clear flags
             Else     /* lift-off */
                If selection method == Lift Off
                   Call Send_Stable_Data()
                Endif
          Endif

Send_stable_data

          Procedure Send_Stable_Data
             If already sent
                Return()
             Else
                Call Check_Buffer_For_Stable_Region()
                If Stable Region Detect flag
                   Current x,y = Stable x,y
                   Set flags
                   Return()
                Else
                   Return()
                Endif
             Endif
          EndProc

Check_Buffer_For_Stable_Region

          Procedure Check_Buffer_For_Stable_Region
             Stable Ref Point x,y = Buffer Head x,y
             Reset count, buffer index
             While points left in buffer
                Get buffer x,y
                If ( Modulus( buffer x,y - Stable Ref Point x,y ) < Tolerance
                   count ++
                   If count >= Stable Region Size
                      Stable Region x,y = Average x,y over stable region
                      Set Stable Region Detect flag
                      Return()
                   Endif
                Else
                   Stable Ref Point x,y = current x,y
                   Reset count, buffer index
                Endif
             EndWhile
          Endproc

CLICK LOCKING

Click locking is the process by which the touch (x,y) coordinate gets locked onto a value before being sent to the system as emulated mouse data.

Note: Click locking only affects touch data when it is sent as emulated mouse data and does not interfere with the normal use of an IBM PS/2 mouse if one is attached to the IBM PS/2 Touch Display 8515, or the data sent in full touch pointing mode.

Click locking is performed because some actions which are done with the mouse button being clicked require that little movement of the mouse pointer itself should take place. Click locking makes the action of double clicking using the touch display easier as it removes the need to maintain the touch position at exactly the same point between clicks.

Prime examples of this can be found in OS/2 Presentation Manager:

  • Clicking on an icon to bring up the system menu, or double clicking to activate the window.
The first of these actions, when attempted with the touch display emulating the mouse can occasionally result in the icon simply moving a few pixels, as the PM shell will misinterpret the 'click down with associated movement' as a drag operation to move the icon. This is because it decides that if the movement is more than a few pixels it must be click with drag rather than a simple click.
Thus even a single click action is sometimes unsuccessful. Even less successful will be the double click action: even if the first click can be done without causing the icon to move, the second click must be done at the same position (actually PM allows a small movement of 6 pixels in the x direction and 8 pixels in the y direction). With a great deal of practice, this condition can be met, but perhaps with only a 20% success rate (tip: for least x,y movement the force variation should be kept to a minimum. In other words, don not press harder than necessary to achieve the button down threshold, and do not lift off completely between clicks, rather just release sufficiently to go below the button up threshold). The normal outcome of such an attempted action is that the icon will move and/or the system menu will appear.
It is this difficulty, of maintaining the x,y position while button clicking, that click locking attempts to remedy. While being mainly applicable to PM, the technique is also useful in the DOS 4.0 shell, or indeed any application (usually in graphics mode) that uses the mouse.

The three click locking options that may be chosen are:

No click locking
Single click locking
Double click locking

NO CLICK LOCKING

Using this option, click locking may be turned off altogether, in which case the system sees the touch coordinates directly as mouse coordinates.

SINGLE CLICK LOCKING

This option locks the (x,y) coordinates as soon as the button down threshold has been exceeded. All subsequent touch coordinates will then be reported to the system with this (x,y) value when sent as emulated mouse data.

Normal reporting of (x,y) coordinates will resume:

  • After the click lock time has been exceeded.
  • If the touch coordinate moves outside the click lock area
  • If the touch is removed from the screen.

DOUBLE CLICK LOCKING

This option is the same as single click locking, except that the conditions for normal reporting of (x,y) data are:

  • After the click lock time has been exceeded.
  • If the touch coordinate moves outside the click lock area
  • If the button down threshold is exceeded for a second time, the touch having been taken below the button up threshold in the interim period.

The third condition enables the (x,y) coordinates of two successive touches to be locked at the some value. Note that the touch need not be removed from the screen completely, it being sufficient to just go below the button up threshold.

CLICK LOCK AREA

This value determines the size of one side of a square which defines the click lock area. The centre of the square is located at the (x,y) position at which the coordinates become locked. When the touch coordinate moves outside the click lock area, normal (x,y) reporting is resumed.

The value is in pixel units, and will therefore vary with screen resolution if a click lock area of a given physical dimension is required.

A large value will make double clicking at a point very easy, but at the expense of making immediate minor adjustment/close manipulation by dragging slightly more cumbersome.

CLICK LOCK TIME

This value determines the time which is allowed to elapse from the time the coordinates first become locked to when normal (x,y) reporting is resumed.

A large value will make double clicking a more unhurried process, but at the expense of making immediate minor adjustment/close manipulation by dragging slightly more cumbersome.

PSEUDOCODE

          Constants:
                     x_limit  = limit of allowed movement in x direction
                     y_limit  = limit of allowed movement in y direction
                     timeout  = limit of time between successive clicks
                     click_type = number of successive clicks to lock over

          Variables:
                     sd_count = number of successive clicks being locked over
                     sd_time  = system time at which timeout will occur
                     sd_x     = initial button down x position
                     sd_y     = initial button down y position
                     x        = current reported x position
                     y        = current reported y position

          Initial state:
                     sd_count = 0

On entry to the procedure the x,y values are set to the current x,y coordinate report. A bit in a status word (selection detection bit) reflects the binary state of the emulated mouse button (1= button down 0= button up).

          /* check if click locking active and still valid:
             if so lock the coordinate
             else reset the process
          */

          If sd_count != 0

             /* if click locking currently active */

             If sd_time > current time
                && modulus(x - sd_x) < x_limit
                && modulus(y - sd_x) < y_limit

                /* if not timed out and within lock area */
                /* force current x,y position to first click position */
                x = sd_x
                y = sd_y

                If button going up
                   && (sd_count >= click_type)

                   /* if the 'button' is being released and required */
                   /* number of clicks reached */
                   sd_count = 0       /* reset the click locking process */
                Endif

             Else

                /* timed out or moved outside lock area: reset click locking */
                sd_count = 0

             Endif
          Endif

          /* check if button going down to increment sd_count,
             thereby starting click locking if it was previously 0
             or incrementing towards the required number of clicks if not
          */

          If button going down

             /* re-initialise timeout time on each button down */

             sd_time = current time + timeout

             If sd_count == 0

                /* if this is the first button down, set the lock coordinates
                   to the current x,y values */

                sd_x = x
                sd_y = y

             Endif

             sd_count++         /* increment click count */

          Endif