IBM PS/2 8516 Touch Display Device Driver Support

From OS2World.Com Wiki
Jump to navigation Jump to search

7th September 1992

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 */

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:

  1. PM does not acknowledge the existence of any other input devices other than keyboard and mouse.

This gives rise to two sub-problems:

  1. How to drive the PM shell itself with an input device other than the keyboard or mouse?
  2. 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:

1. 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:

1. If the maximum number of elements in the queue

   have been altered by TdiSetQueueSize, then
   this function will reflect that as the new
   maximum.

2. 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:

1. 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.

2. 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:

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 the
   TdiGetCoordSys() call) is used.

4. X,Y and Z values can be in the range -32768 to

   +32767.

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 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:

1. 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:

1. 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.

2. 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:

1. 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.

2. 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').


3. 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.

 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 -  | Reserved                               |
| 5Fh   |                                        |
+-------+----------------------------------------+
| 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:

o 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.

o 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.

o 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:

o 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