IBM PS/2 8516 Touch Display Device Driver Support

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:

o  A touch device independent subsystem

o  A touch device driver

o  A touch device dependent subsystem

o  A combined IBM PS/2 Mouse/touch device dependent device driver

o  A touch virtual device driver

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

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

o  Device dependent features (only) accessed by    PM control panel or device driver load time parameters (using common TOUCH.INI file).

o  PM mouse emulation support for windowed DOS sessions.

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

API'S
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.

32BIT 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       valid filename           none download into Touch Display

-  INIT=        Parameter file to       valid filename           none over-ride default settings in                  device driver

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:

o  Force Thresholds

o  Mouse emulation on|off control

o  Mouse emulation beep feedback (on button down) on|off control

o  Mouse emulation Click lock parameters

o  Mouse emulation XY finger - pointer offset

o  Data packet report rate

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

o  No provision for button 2 emulation (button 2    now being defined by CUA for direct    manipulation).

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

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.

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)

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

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

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

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

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

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 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 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
 * 0CH - Set coordinate system
 * 10H - Set coordinate origin
 * 58H - Get coordinate system
 * 5CH - Get coordinate origin

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:

o  Process packet

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

o  Query Configuration

o  Enable Read

o  Disable Write

o  Enable Device

o  Disable Device

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

o  Register VDD

o  Query configuration

o  Set emulation state

o  Disable

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

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:

o  At create time, VDD installs interrupt vector hook (InstallHookVect)

o  Interrupt vector table gets patched with address A

o  Address A points to an illegal real mode instruction (ARPL)

o  Software interrupt causes transfer to address A

o  Execution of the ARPL located there instruction causes a trap

o  OS/2 fields this trap

o  ??? OS/2 looks into a list of procs that are registered for this trap via InstallHookVect and calls each one in turn

o  Hook procs get passed pointer to Client Register Frame

o  Hook procs process call based on registers passed in CRF

o  If Hook procs int then does VDHPopInt (fills    return CS:IP in CRF)

o  Hook procs returns TRUE if its int else FALSE

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

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

o  After the click lock time has been exceeded.

o  If the touch coordinate moves outside the click lock area

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

o  After the click lock time has been exceeded.

o  If the touch coordinate moves outside the click lock area

o  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 