home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / TOUC8516.ZIP / TOUCH.ASC
Text File  |  1992-09-08  |  167KB  |  5,746 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                      IBM PS/2
  11.                 8516 Touch Display
  12.               Device Driver Support
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                  7th September 1992
  21.  
  22.  
  23. Abstract
  24.  
  25.  
  26.  The IBM PS/2 8516 Touch Display Driver Support document attached contains
  27.  information on OS/2 version 2.0 Device Independent API function calls and all
  28.  IOCtl commands. For information on DOS and OS/2 1.2/1.3 API calls please see
  29.  the 8516 Technical Reference (P/N 92F2673).
  30.  
  31.  
  32.  
  33.  
  34. Device driver overview
  35.  
  36. This add-on component to OS/2 2.0 provides support
  37. for the IBM PS/2 8516 Touch Display pointing
  38. device.  IBM PS/2 8516 Touch Display  is
  39. essentially a PS/2 8515 Display, which, besides
  40. the normal video cable connection to a VGA/XGA
  41. port, has a touch data cable which attaches to the
  42. IBM PS/2 Mouse (pointing device) port on the
  43. system unit.  In addition, the monitor itself has
  44. a socket to which the IBM PS/2 Mouse  may
  45. optionally be attached.
  46.  
  47. Support for IBM PS/2 8516 Touch Display  for OS/2
  48. (protected) mode and DOS (real) mode applications
  49. will be provided by six components:
  50.  
  51. o   A touch device independent subsystem
  52.  
  53. o   A touch device driver
  54.  
  55. o   A touch device dependent subsystem
  56.  
  57. o   A combined IBM PS/2 Mouse/touch device
  58.     dependent device driver
  59.  
  60. o   A touch virtual device driver
  61.  
  62. o   An ABIOS RAM extension for both IBM PS/2 Mouse
  63.     and IBM PS/2 8516 Touch Display devices
  64.  
  65.     (Not required for Family 1 machines).
  66.  
  67. Note:
  68.  
  69.        Support for IBM PS/2 8516 Touch Display as
  70.        a video device is provided by standard 8515
  71.        device drivers:  indeed, as far as the
  72.        system is concerned, there is no difference
  73.        video-wise between this monitor and a
  74.        standard 8515.
  75.  
  76. The differences between this support and previous
  77. OS/2 1.2/3 support are:
  78.  
  79. o   Revised touch API which is device independent.
  80.  
  81.     Programs written to the existing TouXXX API
  82.     using device dependent features (thresholds,
  83.     filter type etc.) will, however, remain
  84.     compatible (by virtualising some functions,
  85.     others will become no-ops).
  86.  
  87. o   Device dependent features (only) accessed by
  88.     PM control panel or device driver load time
  89.     parameters (using common TOUCH.INI file).
  90.  
  91. o   PM mouse emulation support for windowed DOS
  92.     sessions.
  93.  
  94. o   VDD gives DOS touch API (INT 7Fh) support for
  95.     multiple full screen DOS sessions.
  96.  
  97.     A DOS property is also available which
  98.     provides 'exclusive touch access' for a
  99.     windowed DOS session.  This disables mouse
  100.     emulation and gives the DOS application direct
  101.     full screen x,y,z touch coordinates.  If the
  102.     DOS session is not maximised to cover the full
  103.     screen then coordinate mapping by the
  104.     application would be required.
  105.  
  106. Figure 1 shows the arrangement of the touch and
  107. mouse device drivers.
  108.  
  109. --------------------------------------------------------------
  110.  
  111.                       Presentation Manager
  112.    MouXXX  A            A      A                                      A  TdiXXX              A TouXXX
  113.    API     |            |      |                                      |  API                 | API
  114.   *--------V--------*   |      |                             *--------V--------*    *--------V--------*
  115.   |   MOUCALLS.DLL  |   |      |                             |   TDICALLS.DLL  <---->   TOUCALLS.DLL  |
  116.   *--------A--------*   |      |                             *--------A--------*    *-----------------*
  117.            |            |      |                                      |
  118.   *--------V--------*   |      |   INT33 DOS             INT7F DOS    *---------*
  119.   |   BMSCALLS.DLL  |   |      |      A  API                 A API              |
  120.   *--------A--------*   |      |      |                      |                  | DosDevIOCtl
  121. DosDevIOCtl|   *--------*      |      |                      |                  |
  122.   *--------V---V----*    *-----V------V----*    *------------V----*    *--------V--------*
  123.   |                 |    |                 |    |                 |    |                 |
  124.   | MOUSE.SYS       |-->-| VMOUSE.SYS      |    | VTOUCH.SYS      |-<--| TOUCH.SYS       |
  125.   |                 |--<-|                 |    |                 |->--|                 |
  126.   |                 |    |                 |    |                 |    |                 |
  127.   |                 |    |                 |    |                 |    |                 |
  128.   *-----------------*    *-----------------*    *-----------------*    *-----------------*
  129.        |       *-------------------<--------*                                  |
  130.        *-----------<------* Emulated mouse  | *------->------------------------*
  131.              Mouse data   A      data       A A   Touch data
  132.                   *-------+-----------------+-+--------*
  133.                   |       |        |     *-------*     |                           (device
  134.  PDITOU02.SYS     |       *------* | *---|   E   |     |      *-----------------*   dependent)
  135.  Combined mouse   |           *---------**-------*     <------>   TDDCALLS.DLL  <---->  TDDxxx
  136.  touch device     |           |    I    |              |      *-----------------*       API
  137.  dependent driver | PDIMOU$   *---------*   PDITOU$    |
  138.                   *----------------+-------------------*
  139.                                    A
  140.                            *-----------------*
  141.               TOUMOUSx.BIO |     ABIOS       |
  142.                            *-----------------*
  143.                                    A
  144.                                    |
  145.                        Mouse/touch display hardware
  146.  
  147.  
  148.  
  149. ------------------------------------------------------------------------------
  150. Figure 1. Schematic diagram of touch/mouse device drivers and subsystems
  151.  
  152. Notes:
  153.  
  154. 1.  The box marked I is the interrupt handler
  155.     which decides whether the data packet is mouse
  156.     or touch data.
  157.  
  158. 2.  The box marked E is controlled by the state of
  159.     mouse emulation.  Data is either passed to the
  160.     mouse or touch device driver depending on
  161.     whether mouse emulation is on or off
  162.     respectively.
  163.  
  164. Note how both the IBM PS/2 Mouse and IBM PS/2 8516
  165. Touch Display devices share the same ABIOS and
  166. device dependent driver.  These components are not
  167. separable due to the access of the devices through
  168. the same physical I/O ports on the 8042, and
  169. sharing the same physical hardware interrupt
  170. request IRQ12h.  This implies a common device
  171. driver with a single interrupt handler, which
  172. decides by examination of the actual data itself,
  173. which device was responsible for the interrupt.
  174.  
  175. Note also that the physical arrangement of the
  176. mouse drivers, where only one device dependent
  177. driver may attach to the device independent
  178. driver, which means that if a mouse other than the
  179. IBM PS/2 Mouse is used in conjunction with IBM
  180. PS/2 8516 Touch Display (for example the Microsoft
  181. Mouse attached to the serial port), either the
  182. serial mouse device dependent driver can attach to
  183. mouse.sys, or the combined driver can attach to
  184. mouse.sys (this being controlled by the device
  185. name specified in the TYPE= keyword of the
  186. DEVICE=MOUSE.SYS config.sys entry).
  187.  
  188. In the former case, the mouse emulation facility
  189. is not available, however the combined driver, can
  190. still attach to just the touch device independent
  191. driver, such that the two devices, mouse and
  192. touch, are completely separate, with the touch
  193. device only available to applications written to
  194. the touch API's.
  195.  
  196. In the latter case, the physical mouse would not
  197. be operable, though the touch device mouse
  198. emulation facility would function.
  199.  
  200. The use of a mouse other than the IBM PS/2 Mouse
  201. therefore, does not preclude the use of the touch
  202. screen when used with specifically written touch
  203. applications, though it does mean that mouse
  204. emulation by the touch screen, for example to
  205. drive Presentation Manager using touch, is not
  206. available (unless the physical mouse is disabled).
  207.  
  208.  
  209. API'S
  210. _____
  211.  
  212. To access the touch display device, DOS mode
  213. applications use the software interrupt 7FH
  214. (INT7FH) interface described under "DOS Device
  215. Dependent API," while OS/2 mode applications use
  216. the Tdixxx API described under "OS/2 Device
  217. Independent Subsystem and API." OS/2 mode
  218. applications may not use the INT7FH API nor may
  219. DOS mode applications use the Tdixxx API.
  220.  
  221. The TouXXX API provided in OS/2 1.2/3 is also
  222. available, but due to the fact that all of the
  223. hardware dependent functions have been moved out
  224. of the TOUCH.SYS driver into the PDITOU0x.SYS
  225. driver, thus making the TOUCH.SYS driver truly
  226. 'device independent'
  227.  
  228. Besides the touch device capability, it is also
  229. possible to use the touch display to emulate the
  230. IBM PS/2 Mouse.  In this case the standard mouse
  231. INT33H API (for DOS mode) and MOUxxx API (for OS/2
  232. mode) are used.
  233.  
  234.  
  235. 32BIT PROGRAMMING
  236.  
  237. The API's described above are 16bit API's, there
  238. are is no 32bit API available for the touch
  239. device.  Programs compiled for the 32 bit flat
  240. model (CL386 -G3 switch) may still use the 16 bit
  241. API calls using the CL386 compiler's built in
  242. 16->32 bit conversions.  These are brought into
  243. play when pointer parameters and function calls
  244. are declared with the "_far16" keyword.  The
  245. complier then generates the necessary 'thunking'
  246. code to perform the call.
  247.  
  248. For further information see the OS/2 2.0 Toolkit
  249. documentation, Appendix headed "Mixed Model
  250. Programming", section headed "Calling from 32-bit
  251. code to 16-bit API's".
  252.  
  253.  
  254. PRESENTATION MANAGER
  255.  
  256. Within Presentation Manager it is not possible to
  257. access the touch device as such from a:
  258.  
  259. 1.  Presentation Manager program
  260.  
  261. 2.  AVIO window
  262.  
  263. 3.  DOS window
  264.  
  265.     This is the default setting.  Using the
  266.     'Properties' option on the System Menu, an
  267.     option has been added called 'Touch: exclusive
  268.     to a window' which disables mouse emulation
  269.     under PM and gives the touch x,y,z data
  270.     directly to the window designated.  The window
  271.     will, however, receive full screen touch
  272.     coordinates and will need to perform a mapping
  273.     unless, for example, it is a graphics program
  274.     running maximised which covers the full
  275.     screen.
  276.  
  277. In these cases mouse emulation mode must be used.
  278.  
  279. Q. What happens when a DOS program is started in a
  280. window and then switched to full screen?
  281.  
  282. Q. And can a full screen program be switched to a
  283. window?
  284.  
  285. For answers to these questions see the discussion
  286. under "INT 7Fh support."
  287.  
  288.  
  289. MOUSE EMULATION
  290. _______________
  291.  
  292. Mouse emulation is performed by the combined
  293. touch/mouse device dependent driver, where instead
  294. of reporting touch event x,y,z data to the
  295. TOUCH.SYS driver, the touch event is converted
  296. into an equivalent mouse event and reported to the
  297. MOUSE.SYS driver.
  298.  
  299. To allow this to happen, the MOUSE.SYS driver has
  300. two IDC entry points for the reporting of data,
  301. one being the conventional entry point where real
  302. mouse events are reported, the other where an
  303. absolute pointing device such as the touch screen
  304. can call directly with absolute x,y values instead
  305. of the normal dx,dy relative mouse movement (in
  306. Mickeys) values.
  307.  
  308. The emulation is being performed at the junction
  309. between the device dependent and independent
  310. drivers, so that at the interfaces of the
  311. MOUSE.SYS driver which are exposed to the outside
  312. world (IOCtl, MouXXX API, INT33h API), no
  313. difference can be detected between the emulated
  314. mouse device and a real mouse device.  The device
  315. independent driver is just that - it hides the
  316. differences between the different sorts of mice
  317. that can attach to the system, which may in fact
  318. be real mice, or could equally be tracker balls,
  319. tablets, touch screens, light pens - or even a
  320. voice recognition system!
  321.  
  322. This implementation also allows flexibility in
  323. that the mouse and touch screen may be used
  324. independently, the touch screen may be used on its
  325. own to emulate the mouse (though without button 2
  326. capability), or the touch screen may be used to
  327. emulate the mouse with simultaneous use of the IBM
  328. PS/2 Mouse itself.
  329.  
  330. Differences:
  331.  
  332.      OS/2 2.0 support and OS/2 1.2/3 support.
  333.  
  334. 1.  Mouse emulation is no longer performed on a
  335.     'per session' basis.  Mouse emulation is now
  336.     on or off system wide, turning mouse emulation
  337.     off using the Touch Control Panel will affect
  338.     all other sessions.
  339.  
  340.     VDM's do, however, have individual mouse
  341.     emulation states: which means that if mouse
  342.     emulation is on system wide, VDM's can choose
  343.     to have mouse emulation on or off individually
  344.     (this is because the DOS INT7Fh API has its
  345.     own mouse emulation on/off control function,
  346.     and we want to virtualise this on a per VDM
  347.     basis, so turning mouse emulation off in one
  348.     VDM does not affect the emulation state in
  349.     another).
  350.  
  351. 2.  Mouse emulation is available when the touch
  352.     display device is reporting touch data:
  353.     opening of the touch device turns off mouse
  354.     emulation by default, but mouse emulation may
  355.     be turned back on while the device is still
  356.     open as a touch device.  Each touch event then
  357.     becomes two events: one touch and one emulated
  358.     mouse event.
  359.  
  360.     This facility was available, but using an
  361.     extra bit in the TouSetEmulOnOff() input
  362.     parameter. It was also further complicated by
  363.     the fact that, for a given session, there were
  364.     two independent sets of hardware parameters:
  365.     touch and mouse emulation, where, for example,
  366.     different touch thresholds could apply in a
  367.     session depending on whether mouse emulation
  368.     was active or not).  The new system is much
  369.     cleaner to implement and easier to understand
  370.     in this respect.
  371.  
  372.  
  373. DEVICE DRIVER INSTALLATION
  374. __________________________
  375.  
  376. The touch display shares the auxiliary device
  377. (mouse) port on the PS/2 with the IBM PS/2 Mouse
  378. by allowing the IBM PS/2 Mouse to connect to the
  379. touch display which is itself connected to the
  380. PS/2.
  381.  
  382. With the IBM PS/2 Mouse and touch display
  383. connected to the auxiliary device port, existing
  384. IBM PS/2 Mouse ABIOS and device drivers will
  385. continue to function as normal, requiring no
  386. changes.
  387.  
  388. However, to access the touch display via the touch
  389. display device driver, the following must be done:
  390.  
  391. 1.  IBM PS/2 Mouse ABIOS must be replaced/extended
  392.  
  393.     This is done by using an ABIOS RAM extension
  394.     contained in the file TOUMOUSx.BIO.  The
  395.     system file ABIOS.SYS needs to be modified to
  396.     include this file in its list of ABIOS
  397.     extensions.  This ABIOS extension adds one
  398.     function to the mouse ABIOS interface to allow
  399.     the touch display to be controlled.
  400.  
  401. 2.  device dependent IBM PS/2 Mouse driver must be
  402.     replaced
  403.  
  404.     The DD file PDIMOU02.SYS is replaced by
  405.     PDITOU02.SYS.  This is done by modifying the
  406.     entry in CONFIG.SYS (see below).
  407.  
  408. 3.  CONFIG.SYS entries for the mouse are modified
  409.  
  410.     An entry for the combined mouse/touch device
  411.     dependent driver is made:
  412.  
  413.  
  414.         Format  DEVICE=PDITOU0x.SYS CODE=TOUCO21D.BIN INIT=TOUCH.INI
  415.  
  416.     where TOUCO21D.BIN is the Touch Display microcode binary file
  417.           TOUCH.INI is a text file containing default parameter settings
  418.  
  419.  
  420.     The following table describes the CONFIG.SYS
  421.     DEVICE= keyword parameters for the combined
  422.     mouse/touch device dependent driver.
  423.  
  424.  
  425.    Keyword      Function                Parameter Range          Default
  426.    ---------------------------------------------------------------------
  427.    CODE=        Microcode file to       valid filename           none
  428.                 download into
  429.                 Touch Display
  430.  
  431.    ---------------------------------------------------------------------
  432.    INIT=        Parameter file to       valid filename           none
  433.                 over-ride default
  434.                    settings in
  435.                    device driver
  436.  
  437.  
  438.     An entry for the touch device independent
  439.     driver is made:
  440.  
  441.  
  442.            Format       DEVICE=TOUCH.SYS TYPE=PDITOU$ [QSIZE=] [SEL=]
  443.  
  444.            Example      DEVICE=TOUCH.SYS TYPE=PDITOU$ QSIZE=15
  445.  
  446.  
  447.     An entry for the mouse device independent
  448.     driver is made:
  449.  
  450.  
  451.            Format       DEVICE=MOUSE.SYS TYPE=PDIMOU$ [QSIZE=]
  452.  
  453.            Example      DEVICE=MOUSE.SYS TYPE=PDIMOU$ QSIZE=15
  454.  
  455.       Note that the device type must be PDIMOU$.
  456.  
  457.  
  458.     The entry for the device dependent mouse/touch
  459.     device driver must precede the other two
  460.     entries, for which the order of appearance is
  461.     not important.
  462.  
  463.     The following table describes the common
  464.     CONFIG.SYS DEVICE= keyword parameters for the
  465.     device independent mouse and touch drivers.
  466.  
  467.    Keyword      Function                Parameter Range          Default
  468.    ---------------------------------------------------------------------
  469.    QSIZE=       OS/2 mode support       1 - 100 elements         10
  470.                 event queue size in
  471.                    elements
  472.    ---------------------------------------------------------------------
  473.    TYPE=        Indicates device        PDITOU$ for touch
  474.                 (dependent) name        PDIMOU$ for mouse
  475.  
  476.  
  477.     The following table describes the unique
  478.     CONFIG.SYS DEVICE= keyword parameters for the
  479.     touch device independent driver.
  480.  
  481.  
  482.    Keyword      Function                Parameter Range          Default
  483.    ---------------------------------------------------------------------
  484.    SEL=         Selection mechanism     Selection type  0-5       0
  485.                 in protected and real   # of stable points 0-40
  486.                 mode                    Tolerance value 0-4095
  487.                                            Search Limit 0-40
  488.  
  489.  
  490.  
  491.     An entry for the touch virtual device driver
  492.     is made:
  493.  
  494.  
  495.            Format       DEVICE=VTOUCH.SYS
  496.  
  497.            Example      DEVICE=VTOUCH.SYS
  498.  
  499.  
  500.  
  501.     There are no keyword parameters for the touch
  502.     virtual device driver.
  503.  
  504.     An entry for the mouse virtual device driver
  505.     is made:
  506.  
  507.  
  508.            Format       DEVICE=VMOUSE.SYS
  509.  
  510.            Example      DEVICE=VMOUSE.SYS
  511.  
  512.  
  513.  
  514. Note that the handling of threshold parameter
  515. changes, filter frequencies and click locking
  516. parameters is either done through the PM Touch
  517. Control Panel (see "Touch Control Panel") or the
  518. TOUCH.INI parameter file (see below).
  519.  
  520.  
  521. FORMAT OF TOUCH.INI PARAMETER FILE
  522.  
  523. A TOUCH.INI parameter file is supplied containing
  524. the defaults device driver settings for:
  525.  
  526. o   Force Thresholds
  527.  
  528. o   Mouse emulation on|off control
  529.  
  530. o   Mouse emulation beep feedback (on button down)
  531.     on|off control
  532.  
  533. o   Mouse emulation Click lock parameters
  534.  
  535. o   Mouse emulation XY finger - pointer offset
  536.  
  537. o   Data packet report rate
  538.  
  539. o   Low pass filter setting
  540.  
  541. The file contents over-ride the built in device
  542. dependent driver settings using the
  543. 'INIT=filename' keyword in the DEVICE= config.sys
  544. entry for the device driver.
  545.  
  546. Any file may be used if it conforms to the
  547. TOUCH.INI syntax: the Touch Control Panel will use
  548. and update the same file referred to by the
  549. config.sys entry.
  550.  
  551. The following shows the format of the TOUCH.INI
  552. file containing the default settings:
  553.  
  554.   /*
  555.    * TOUCH.INI - 8516 Touch Display Device Dependent
  556.    * Driver Initialization File
  557.    *
  558.    */
  559.  
  560.   /* The format of this file is as follows:
  561.    *
  562.    * One Key Word per line followed by an equals sign then the arguments,
  563.    * no duplicate tokens allowed
  564.    *
  565.    * All spaces & tabs are ignored
  566.    * Arguments are delimited with commas
  567.    *
  568.    * To set an option OFF use 0
  569.    * To set an option ON  use 1
  570.    *
  571.    * Two types of comment are supported.
  572.    * They conform to the 'C' programming
  573.    * language syntax. Nested comments, in any form, are not supported.
  574.    *
  575.    */
  576.  
  577. THRESH  = 46, 80, 96    // Thresholds [on-screen, push-hyst, push-thresh]
  578. CLICK   = 2, 300, 500   // Click Locking [type, size, time]
  579. XYOFF   = 0, 0          // XY Offset [x-off, y-off]
  580. RATE    = 3             // Report Rate [rate]
  581. EMUL    = 1             // Mouse Emulation [on/off]
  582. BEEP    = 1             // Emulation Beep on selection [on/off]
  583. FILT    = 0, 0          // Low pass filter type, speed
  584. //MPI   = 200           // (internal use only!)
  585.  
  586.   /* end-of-file */
  587.  
  588.  
  589.  
  590. CALIBRATION UTILITY INSTALLATION
  591.  
  592. The calibration utility performs the dual function
  593. of downloading calibration constant data to the
  594. touch display every time the system unit is
  595. powered on and allowing re-calibration of the
  596. touch display (on initial setup, when the display
  597. is moved to a new location etc.).
  598.  
  599. For this reason it should be inserted into the
  600. config.sys file where it will run automatically
  601. every time the system unit is powered on (or
  602. indeed warm booted, although this is not strictly
  603. necessary).  An entry in config.sys is made so:
  604.  
  605.  
  606.      run=c:\touchos2\calibrat.exe -c calibrat.dat
  607.  
  608.  
  609. If the calibrat.dat file is not found (when the
  610. display is initially installed for instance), the
  611. operator will be prompted for action to
  612. re-calibrate the display, and if successful a new
  613. calibrat.dat file will be created.
  614.  
  615. The calibration utility may be run from the OS/2
  616. command line at any time, for example to
  617. re-calibrate the display:
  618.  
  619.  
  620.      c:
  621.      cd \touchos2
  622.      calibrat -u
  623.  
  624.  
  625. Note the use of the '-u' option which will allow
  626. an existing calibrat.dat file to be updated with
  627. new calibration data.
  628.  
  629.  
  630. Presentation Manager and Touch: A Guided Tour
  631.  
  632. Unlike the PS/2 mouse, there is no in-built
  633. support for a Touch device in PM.  This has
  634. implications both for true PM applications and
  635. also full-screen applications that wish to become
  636. window-able.  There are further complications when
  637. multiple DOS applications become window-able.
  638.  
  639.  
  640. PAST HISTORY: THE MOUSE
  641. _______________________
  642.  
  643. To begin with, let us consider what has been done
  644. with the mouse.
  645.  
  646.  
  647. OS/2 1.0
  648.  
  649. With OS/2 1.0, only full screen applications were
  650. possible, each running in a separate screen group.
  651. The application made use of the MouXXX calls API
  652. (or INT33h API if running in the DOS 3.x
  653. compatibility box), and was able to behave as
  654. though it were the only application using the
  655. mouse.
  656.  
  657. The Mouse device driver maintained a separate
  658. state for each screen group, so that when
  659. switching between screen groups, it would save and
  660. restore the states appropriate for each screen
  661. group.  In this way, applications were isolated
  662. from each other and able to operate without mutual
  663. interference.
  664.  
  665. Only the foreground screen group, however, was
  666. permitted access to the mouse:  any application
  667. making an MouXXX call while running detached in
  668. the background would have the call fail with an
  669. error.
  670.  
  671.  
  672. OS/2 1.1
  673.  
  674. With OS/2 1.1 came the Presentation Manager screen
  675. group, where multiple applications can be run in
  676. one screen group, under the overall control of the
  677. Presentation Manager desktop/shell.  The
  678. application could either be a new application,
  679. written to use the new PM API, or it could be a
  680. port of an existing full-screen text application
  681. working within a PM text window.  Full-screen
  682. applications could still run in a separate
  683. full-screen screen group as before in OS/2 1.0.
  684.  
  685. To run in a PM window, however, text mode
  686. applications had to conform to certain
  687. restrictions and rules.  Essentially, these
  688. preclude any action by one program in the PM
  689. screen group having an unintended adverse effect
  690. on any other, including the PM shell itself, and
  691. other text window applications or true PM
  692. applications.  These restrictions affect not only
  693. the mouse, but also the keyboard and screen I/O
  694. where similar restrictions apply.
  695.  
  696. To accomplish this, the PM shell assumes
  697. responsibility on behalf of all the applications
  698. running under it for the Mouse device, in terms of
  699. how the mouse and associated device driver is
  700. configured (eg absolute coordinate report range,
  701. scaling factor, pointer image shape etc.).  It
  702. does this by providing a replacement mouse
  703. subsystem for that screen group to handle the
  704. MouXXX calls that applications may make.  It can
  705. then control the way in which the application has
  706. access to the Mouse device.
  707.  
  708. (Note that applications which do not conform, for
  709. example by direct IOCtl commands to the device
  710. driver, or (??#@%$!) commands direct to the
  711. hardware are likely to cause unpredictable
  712. behaviour of the Mouse device within PM as a
  713. whole).
  714.  
  715. Applications written to the PM API would not
  716. normally make any MouXXX calls (although they are
  717. not explicitly stopped from doing so, for example
  718. to query the number of buttons the mouse has),
  719. rather they rely on receiving messages from PM
  720. indicating when the users mouse input is directed
  721. at them as a window rather than any other program
  722. running or the PM shell itself.
  723.  
  724. One of the consequences of running in a window is
  725. that the physical screen coordinates and
  726. application coordinates do not coincide, as the
  727. application window may be moved or sized to any
  728. position on the screen.  However, the PM shell has
  729. the information required to accomplish the
  730. transformation, so that applications, including
  731. text window applications are given the correct
  732. coordinates.
  733.  
  734. Effectively the 'state' of the mouse and mouse
  735. driver is fixed for all applications running under
  736. PM.  As an example, the mouse device driver is
  737. configured by PM to return data in absolute
  738. coordinate reporting format:  any text window
  739. program requiring data in relative reporting
  740. format will find it is unable to make the Mou call
  741. successfully to accomplish this.  To allow the
  742. call would cause PM to lose track of where the
  743. mouse pointer was, thereby creating havoc.
  744.  
  745. In this way then the PM screen group manages to
  746. run several applications at once, all able to use
  747. the mouse device, as well as itself.  It does this
  748. at the expense of allowing each application total
  749. control over the mouse device which it was
  750. previously able to enjoy when running in a
  751. separate full-screen screen group.
  752.  
  753.  
  754. TODAY: THE TOUCH DEVICE
  755. _______________________
  756.  
  757.  
  758. FULL-SCREEN SCREEN GROUP
  759.  
  760. For the Touch device things are no different than
  761. they are for the mouse where applications running
  762. in a full-screen screen group are concerned.
  763. There is a TdiXXX (Int 7Fh in the DOS box) API
  764. which provides full access to the device hardware.
  765. Applications are isolated from each other by
  766. running in a separate screen group, the state of
  767. which is maintained separately by the device
  768. driver, which saves and restores the states as
  769. screen group switching takes place.
  770.  
  771.  
  772. PRESENTATION MANAGER SCREEN GROUP
  773.  
  774. In PM there is one problem to be addressed:
  775.  
  776. 1.  PM does not acknowledge the existence of any
  777.     other input devices other than keyboard and
  778.     mouse.
  779.  
  780. This gives rise to two sub-problems:
  781.  
  782. 1.  How to drive the PM shell itself with an input
  783.     device other than the keyboard or mouse?
  784.  
  785. 2.  How to allow applications concurrent use of
  786.     the Touch device if PM is not in complete
  787.     control as it is with the mouse?
  788.  
  789. The issue can be sidestepped by providing an
  790. emulation of the Mouse device by the Touch device.
  791. This has the advantage that all existing
  792. applications that currently use the Mouse will
  793. work with Touch (including the PM shell).  This
  794. assumes that all Mouse actions can be emulated by
  795. the Touch device.  It may not be the case as in:
  796.  
  797. o   No provision for button 2 emulation (button 2
  798.     now being defined by CUA for direct
  799.     manipulation).
  800.  
  801. o   Double clicking may be difficult to achieve in
  802.     practice (requirement for a stable x,y
  803.     position being a particular problem).
  804.  
  805.     This problem can be circumvented to some
  806.     extend by use of 'click locking' which
  807.     effectively performs the task of locking the
  808.     touch coordinates onto a single value when
  809.     button clicking is being attempted.
  810.  
  811. Alternatively, a solution may be sought that does
  812. not involve a change to PM.  One approach is to
  813. write a 'Touch manager' component that assumes
  814. control of the Touch device, perhaps replacing the
  815. subsystem to prevent direct access to the device.
  816. The Touch manager then processes the touch data
  817. events, issuing new style Touch messages as well
  818. as Mouse messages to PM applications, Mouse/System
  819. messages to the PM shell/control windows and also
  820. providing Touch coordinate data to windowed text
  821. applications (suitably transformed to take account
  822. of window sizing and placement).
  823.  
  824. One solution in this vein (AUI) clearly worked,
  825. but the developers still felt that the only real
  826. solution was an open architecture scheme for the
  827. input device management of PM that would allow
  828. support for all current input devices as well as
  829. extensibility for future devices.
  830.  
  831.  
  832. IBM PS/2 8516 TOUCH DISPLAY POSITION
  833.  
  834. Currently IBM PS/2 8516 Touch Display offers what
  835. might be termed a 'reasonable' attempt at mouse
  836. emulation (but no button 2), where mouse movement,
  837. button clicking, dragging and double clicking are
  838. all possible.
  839.  
  840. As far as full touch mode is concerned, any
  841. application has full access to the Touch device,
  842. bearing in mind that since there are no
  843. restrictions placed on the TdiXXX calls that may
  844. be made, applications have to be self-regulatory,
  845. otherwise they may conflict.  Note, however, that
  846. if PM were 'Touch aware', it would be making a
  847. similar set of restrictions on the use of the
  848. TdiXXX API as it does with the MouXXX API, so
  849. nothing is effectively being lost in this respect.
  850.  
  851. Even the ability to write a PM application using
  852. the Touch device in the same manner as the Mouse
  853. device (via messages) is available to the
  854. application by writing a 'Touch manager' either as
  855. part of the application or stand alone using
  856. private messages.
  857.  
  858.  
  859. TOUCH APPLICATIONS IN PM
  860.  
  861. An existing product which supports Touch input in
  862. PM, Executive Decisions, has already shown that
  863. the requirements for Touch are different than for
  864. Mouse (icons/selection items must be larger,
  865. program runs as a PM window occupying the full
  866. screen with the user never having to see the
  867. normal PM desktop).
  868.  
  869. This indicates that the 'solution' for Touch in
  870. PM, if such a thing exists, not only involves
  871. changes to the PM architecture to allow new input
  872. devices, but also the appearance of the desktop
  873. (eg allow scroll bar size to be configured when
  874. sizing a window) and the way in which it can be
  875. manipulated (CUA definitions for keyboard and
  876. mouse to extended certainly for touch, and perhaps
  877. also to include a 'generic' input device type
  878. (which could be the mouse)).
  879.  
  880.  
  881. Design notes
  882.  
  883. CURRENT STATE OF AFFAIRS: OS/2 1.2/3
  884. ____________________________________
  885.  
  886. The parameters which can be affected by the touch
  887. API's are on a per-session basis (including DOS
  888. 3.x box session).  For each session, the device
  889. driver holds a local set of parameters for such
  890. things like: thresholds, coordinate system, event
  891. mask, click lock mechanism, selection detection
  892. mechanism etc.
  893.  
  894. For those parameters which actually cause a change
  895. of state of the hardware (eg thresholds, filter
  896. type etc.), for every session switch the outgoing
  897. session's current parameters are saved and the
  898. incoming session's parameters are restored by
  899. sending commands to the touch display to effect
  900. the changes.
  901.  
  902. While this is a most flexible arrangement,
  903. allowing separate full screen sessions completely
  904. different settings for such things as touch
  905. thresholds, it becomes impossible to provide
  906. support for separate programs running in windows
  907. under Presentation Manager.
  908.  
  909. The current situation allows programs running
  910. under Presentation Manager (either AVIO text
  911. windowed or full PM programs) full access to the
  912. TouXXX API, along with the ability for each
  913. program to unilaterally change the touch
  914. thresholds, coordinate system etc.  Since these
  915. functions directly change the state of the
  916. hardware, we have the situation where programs
  917. sharing the same output device (screen) are
  918. allowed parallel access to a single input device.
  919. Result: chaos (or complete flexibility, depending
  920. on how you view it)!
  921.  
  922.  
  923. CHANGES FOR OS/2 2.0
  924. ____________________
  925.  
  926. What is needed is a single owner of the device
  927. (PM) which them handles it on behalf of its
  928. multiple clients.  However, until PM changes to
  929. support multiple input devices in the way that it
  930. currently only handles keyboard and mouse, nothing
  931. is likely to alleviate this situation.
  932.  
  933. Thus the implementation carries over the dual full
  934. touch/mouse emulation nature of the touch device
  935. support, leaving it up to the application
  936. developer to choose how they wish to use the touch
  937. device.
  938.  
  939. However, some changes have been made to get round
  940. some of the other problems noted with the OS/2
  941. 1.2/3 implementation, and to accommodate the new
  942. features of OS/2 2.0: namely MDVM support.
  943.  
  944.  
  945. TRUE DEVICE INDEPENDENT TDIXXX API
  946.  
  947. It was decided to scrap the ability to access all
  948. the hardware dependent features of the original
  949. TouXXX API and design a new device independent
  950. TdiXXX API.
  951.  
  952. The facility for changing the hardware by an
  953. application has been removed with &cruiser, so
  954. that an application program no longer has the
  955. ability to unilaterally change the touch
  956. thresholds, coordinate system etc.  to the
  957. detriment of other applications running at the
  958. same time.
  959.  
  960. Thus, the TdiXXX API no longer allows access to
  961. hardware dependent features, and indeed, those
  962. hardware dependent calls in the TouXXX API which
  963. is also provided for compatibility with OS/2 1.2/3
  964. are either virtualised or are no-ops.  In either
  965. case, the hardware state is unaffected by these
  966. calls , so that the state of the hardware is
  967. fixed, and can only be altered by using the Touch
  968. Control Panel once the device drivers are loaded.
  969.  
  970.  
  971. MULTIPLE VIRTUAL DOS MACHINE (MVDM) SUPPORT
  972.  
  973. The OS/2 1.2/3 driver followed the same model as
  974. the mouse device driver in providing DOS box
  975. support of the DOS device driver INT7Fh API in the
  976. same way that INT33h is also supported by the
  977. mouse device driver.
  978.  
  979. In the same way, the IBM PS/2 8516 Touch Display
  980. support for OS/2 2.0 includes a virtual device
  981. driver which gives a (virtualised) DOS INT7Fh API
  982. for MVDM's.  Touch events are simulated in the VDM
  983. using IRQ12/INT74 which is shared with the
  984. VMOUSE.SYS when using a PS/2 mouse.  The
  985. extensions to PS/2 mouse BIOS (INT15 AH=C2h) for
  986. touch are not supported in any way.
  987.  
  988. When considering the problems concerned with
  989. accessing the touch device in Presentation
  990. Manager, with OS/2 2.0  the problem extends to DOS
  991. programs running in a window under Presentation
  992. Manager.  The virtual device driver provided will
  993. support the DOS INT7Fh API for MVDM's, but by
  994. default will be limited to making actual touch
  995. x,y,z data available to full screen DOS programs
  996. only.  This is because while running with the
  997. Presentation Manager session in the foreground,
  998. the physical device driver, which handles the
  999. touch data interrupts, cannot decide on its own
  1000. which window to send the touch data to.
  1001.  
  1002. The mouse accomplishes this because it is able to
  1003. feed the PM single queue, then PM decides, based
  1004. upon the event x,y data, which window is to
  1005. receive the event.  If this is a DOS window, it
  1006. calls the virtual device driver.
  1007.  
  1008. For those DOS applications that nevertheless wish
  1009. to receive full screen x,y,z touch data while
  1010. running in a window, a DOS property will be
  1011. provided ('Touch:  exclusive to a window') which
  1012. will effectively turn off mouse emulation and
  1013. direct all touch data to that window.
  1014.  
  1015. This then solves the question of what happens with
  1016. applications that can be switched between full
  1017. screen and windowed - the answer being that while
  1018. the (now device independent) DOS INT7Fh API will
  1019. continue to function in a window, touch data will
  1020. not be available to the application until it is
  1021. switched to full screen.  In all other respects
  1022. the application will function exactly as before.
  1023.  
  1024. DOS mouse applications will, however, not be
  1025. subject to this restriction, being able to run
  1026. with touch input in the form of emulated mouse
  1027. data in a DOS window or full screen.
  1028.  
  1029.  
  1030. OS/2 DEVICE INDEPENDENT SUBSYSTEM AND API
  1031. _________________________________________
  1032.  
  1033.  
  1034. TOUCH DEVICE INDEPENDENT SUBSYSTEM DLL
  1035.  
  1036. The Touch device independent sub-system is
  1037. contained in the TDICALLS.DLL run time file,
  1038. executing on level 3 (application level).  The
  1039. sub-system receives all TDIxxx calls, passing them
  1040. to the Touch Device Independent Device Driver
  1041. which receives control via DosOpen,Close or the
  1042. DosDevIOCtl API.
  1043.  
  1044. The Touch sub-system is similar in many respects
  1045. to the Mouse sub-system, except that it does not
  1046. provide for registering/de-registering extensions
  1047. to the subsystem.
  1048.  
  1049.  
  1050. TDIXXX API
  1051.  
  1052. A new Touch API is provided by the Touch device
  1053. independent sub-system:
  1054.  
  1055.  
  1056.          TdiClose
  1057.          TdiFlushQueue
  1058.          TdiGetCoordSys
  1059.          TdiGetEmulState
  1060.          TdiGetEventMask
  1061.          TdiGetQueueSize
  1062.          TdiGetSelectMethod
  1063.          TdiOpen
  1064.          TdiReadEventQueue
  1065.          TdiSetCoordSys
  1066.          TdiSetEmulState
  1067.          TdiSetEventMask
  1068.          TdiSetQueueSize
  1069.          TdiSetSelectMethod
  1070.  
  1071.  
  1072. Refer to the file TDICALLS.H for C function
  1073. prototypes, structures and #defined constants
  1074. useful for this API.
  1075.  
  1076.  
  1077. TDICLOSE
  1078. ________
  1079.  
  1080. This call closes the touch device for the current
  1081. session.
  1082.  
  1083.  
  1084.          TdiClose(DeviceHandle, rc)
  1085.  
  1086.  
  1087. INPUT PARAMETERS
  1088. ________________
  1089.  
  1090.  
  1091.  
  1092.          Device Handle (HTDI)
  1093.          Handle of the touch device from a previous TdiOpen call
  1094.  
  1095.  
  1096.  
  1097. OUTPUT
  1098. ______
  1099.  
  1100.  
  1101.          rc (USHORT)
  1102.          Return code in register AX
  1103.  
  1104.              0 - NO_ERROR
  1105.  
  1106.  
  1107.  
  1108.  
  1109. TDIFLUSHQUEUE
  1110. _____________
  1111.  
  1112. This function directs the touch driver to flush
  1113. (empty) the touch event queue for the session.
  1114.  
  1115.  
  1116.          TdiFlushQueue(DeviceHandle, rc)
  1117.  
  1118.  
  1119. INPUT PARAMETERS
  1120. ________________
  1121.  
  1122.  
  1123.  
  1124.          Device Handle (HTDI)
  1125.          Handle of the touch device from a previous TdiOpen call
  1126.  
  1127.  
  1128.  
  1129. OUTPUT
  1130. ______
  1131.  
  1132.  
  1133.          rc (USHORT)
  1134.          Return code in register AX
  1135.  
  1136.              0 - NO_ERROR
  1137.                  TDI_ERR_UNKNOWN_COMMAND
  1138.                  TDI_ERR_GENERAL_FAILURE
  1139.  
  1140.  
  1141.  
  1142.  
  1143. TDIGETCOORDSYS
  1144. ______________
  1145.  
  1146. This function returns to the caller the current
  1147. coordinate reporting range and hysteresis used in
  1148. x,y reports.
  1149.  
  1150.  
  1151.          TdiGetCoordSys( CoordSys, DeviceHandle, rc)
  1152.  
  1153.  
  1154. INPUT PARAMETERS
  1155. ________________
  1156.  
  1157.  
  1158.          CoordSys   (PTDICOORDSYS)
  1159.         This is a pointer to a structure of type TDICOORDSYS in which the
  1160.          function returns the coordinate system:
  1161.  
  1162.          Offset      Type         Description
  1163.  
  1164.          0H          USHORT       X minimum value
  1165.          2H          USHORT       X maximum value
  1166.          4H          USHORT       Y minimum value
  1167.          6H          USHORT       Y maximum value
  1168.          8H          USHORT       Z minimum value
  1169.          AH          USHORT       Z maximum value
  1170.          CH          USHORT       X hysteresis value * 1000
  1171.          EH          USHORT       Y hysteresis value * 1000
  1172.  
  1173.  
  1174.  
  1175.          Device Handle (HTDI)
  1176.          Handle of the touch device from a previous TdiOpen call
  1177.  
  1178.  
  1179.  
  1180. OUTPUT
  1181. ______
  1182.  
  1183.  
  1184.          rc (USHORT)
  1185.          Return code in register AX
  1186.  
  1187.              0 - NO_ERROR
  1188.                  TDI_ERR_UNKNOWN_COMMAND
  1189.                  TDI_ERR_GENERAL_FAILURE
  1190.  
  1191.  
  1192.  
  1193. Notes:
  1194.  
  1195. 1.  Hysteresis is the amount, expressed in
  1196.     coordinate report units multiplied by 1000, by
  1197.     which a touch contact must cross the border
  1198.     between adjacent coordinate cells before a
  1199.     change in coordinate report is registered.
  1200.  
  1201. 2.  This is to prevent reports flickering between
  1202.     two values when a touch contact point lies on
  1203.     the border of adjacent coordinate cells.
  1204.  
  1205. 3.  A default hysteresis of 0.5 coordinate units
  1206.     (reported value of 500 using this function) is
  1207.     used.
  1208.  
  1209. 4.  X,Y and Z values must be in the range -32768
  1210.     to +32767.  X axis will increase from left to
  1211.     right if Xmax >  Xmin, or become inverted if
  1212.     Xmin >  Xmax.  Z axis will increase from top
  1213.     to bottom if Ymax >  Ymin, or become inverted
  1214.     if Ymin >  Ymax.
  1215.  
  1216. 5.  Hysteresis values are unsigned integers in the
  1217.     range 0 to 65535.
  1218.  
  1219. 6.  Hysteresis values are expressed in terms of
  1220.     the required hysteresis value, in coordinate
  1221.     system units, multiplied by 1000.
  1222.  
  1223. 7.  Thus to set a hysteresis of 0.5, a value of
  1224.     500 should be used.  The maximum hysteresis
  1225.     that may be set is therefore 65.535 screen
  1226.     units, corresponding to the maximum permitted
  1227.     value 65535.
  1228.  
  1229.  
  1230. TDIGETEMULSTATE
  1231. _______________
  1232.  
  1233. This function returns to the caller the current
  1234. state of mouse emulation.
  1235.  
  1236.  
  1237.          TdiGetEmulState (EmulState, DeviceHandle, rc)
  1238.  
  1239.  
  1240. INPUT PARAMETERS
  1241. ________________
  1242.  
  1243.  
  1244.          EmulState (PUSHORT)
  1245.          This is a pointer to a structure of type USHORT in which the
  1246.          function returns the mouse emulation state:
  1247.  
  1248.          Bit      Description
  1249.  
  1250.           0       Mouse emulation state
  1251.                   =0 = Emulation off, =1 = Emulation on
  1252.           1-F     Reserved (=0)
  1253.  
  1254.  
  1255.          Device Handle (HTDI)
  1256.          Handle of the touch device from a previous TdiOpen call
  1257.  
  1258.  
  1259.  
  1260. OUTPUT
  1261. ______
  1262.  
  1263.  
  1264.          rc (USHORT)
  1265.          Return code in register AX
  1266.  
  1267.              0 - NO_ERROR
  1268.                  TDI_ERR_PARAMETERS_INVALID
  1269.                  TDI_ERR_UNKNOWN_COMMAND
  1270.                  TDI_ERR_GENERAL_FAILURE
  1271.  
  1272.  
  1273.  
  1274. Notes:
  1275.  
  1276. 1.  Under Presentation Manager any program which
  1277.     opens the Touch Display device (TdiOpen)
  1278.     disables mouse emulation for the whole of the
  1279.     Presentation Manager session.  Mouse emulation
  1280.     can be enabled while the touch device is open
  1281.     using TdiSetEmulState(), whence touch data
  1282.     becomes available both as emulated mouse data
  1283.     as well as touch data.
  1284.  
  1285.  
  1286. TDIGETEVENTMASK
  1287. _______________
  1288.  
  1289. This function returns to the caller the current
  1290. touch event queue mask.
  1291.  
  1292.  
  1293.          TdiGetEventMask(EventMask, DeviceHandle, rc)
  1294.  
  1295.  
  1296. INPUT PARAMETERS
  1297. ________________
  1298.  
  1299.  
  1300.          EventMask (PUSHORT)
  1301.          This is a pointer to a structure of type USHORT in which the
  1302.          function returns the event mask:
  1303.  
  1304.  Bit          Description
  1305.  
  1306.    0         1 = report On screen events (On Screen status set)
  1307.    1         1 = report Touch Down events (On Screen status clear to set)
  1308.    2         1 = report Lift Off events (On Screen status set to clear)
  1309.    3         1 = report Selection detection flag set events
  1310.    4         1 = report Selection Detection flag clear to set events
  1311.    5         1 = report Selection Detection flag set to clear events
  1312.    6-F       reserved
  1313.  
  1314.  
  1315.          Device Handle (HTDI)
  1316.          Handle of the touch device from a previous TdiOpen call
  1317.  
  1318.  
  1319.  
  1320. OUTPUT
  1321. ______
  1322.  
  1323.  
  1324.          rc (USHORT)
  1325.          Return code in register AX
  1326.  
  1327.              0 - NO_ERROR
  1328.                  TDI_ERR_PARAMETERS_INVALID
  1329.                  TDI_ERR_UNKNOWN_COMMAND
  1330.                  TDI_ERR_GENERAL_FAILURE
  1331.  
  1332.  
  1333.  
  1334.  
  1335. TDIGETQUEUESIZE
  1336. _______________
  1337.  
  1338. This function returns to the caller the current
  1339. maximum number of elements allowed in a touch
  1340. event queue.  The maximum queue size itself is
  1341. defined by the CONFIG.SYS QSIZE= parameter.
  1342.  
  1343.  
  1344.          TdiGetQueueSize(QueSize, DeviceHandle, rc)
  1345.  
  1346.  
  1347. INPUT PARAMETERS
  1348. ________________
  1349.  
  1350.  
  1351.          QueSize (PUSHORT)
  1352.          This is a pointer to a structure of type USHORT in which the
  1353.          function returns the current queue size:
  1354.  
  1355.          Offset      Type         Description
  1356.  
  1357.          0H          USHORT       Maximum size of the event queue
  1358.  
  1359.  
  1360.  
  1361.          Device Handle (HTDI)
  1362.          Handle of the touch device from a previous TdiOpen call
  1363.  
  1364.  
  1365.  
  1366. OUTPUT
  1367. ______
  1368.  
  1369.  
  1370.          rc (USHORT)
  1371.          Return code in register AX
  1372.  
  1373.              0 - NO_ERROR
  1374.                  TDI_ERR_PARAMETERS_INVALID
  1375.                  TDI_ERR_UNKNOWN_COMMAND
  1376.                  TDI_ERR_GENERAL_FAILURE
  1377.  
  1378.  
  1379.  
  1380. Notes:
  1381.  
  1382. 1.  If the maximum number of elements in the queue
  1383.     have been altered by TdiSetQueueSize, then
  1384.     this function will reflect that as the new
  1385.     maximum.
  1386.  
  1387. 2.  The number of touch events in the queue itself
  1388.     is returned with the TdiReadEventQueue call.
  1389.  
  1390.  
  1391. TDIGETSELECTMETHOD
  1392. __________________
  1393.  
  1394. This function returns to the caller the current
  1395. status of the selection detection flag set/reset
  1396. mechanism.
  1397.  
  1398.  
  1399.          TdiGetSelectMethod(SelectMech, DeviceHandle, rc)
  1400.  
  1401.  
  1402. INPUT PARAMETERS
  1403. ________________
  1404.  
  1405.  
  1406.     Selectmech (PTDISELMECH)
  1407.     This is a pointer to a structure of type TDISELMECH in which the
  1408.     function returns the selection detection flag set/reset mechanism.
  1409.  
  1410.  
  1411.          Offset      Type         Description
  1412.  
  1413.          0H          USHORT       Selection Type
  1414.                                    Bit 0
  1415.                                       0 = Push harder (default)
  1416.                                       1 = Lift Off
  1417.                                    Bit 1
  1418.                                       0 = First value taken
  1419.                                       1 = Single touch algorithm active
  1420.                                    Bit 2
  1421.                                       0 = First value taken
  1422.                                       1 = Stable region algorithm active
  1423.                                    Bit 3 - F
  1424.                                       0 = Reserved
  1425.  
  1426.          2H          USHORT        Number of stable points
  1427.                                     0 = default
  1428.                                     n = # of stable points
  1429.  
  1430.          4H          USHORT        Tolerance value
  1431.                                     0 = default
  1432.                                     n = tolerance in pixels
  1433.  
  1434.          6H          USHORT        Stack length
  1435.                                     0 = default
  1436.                                     n = length in samples ( 0 < n < 60 )
  1437.  
  1438.  
  1439.  
  1440.          Device Handle (HTDI)
  1441.          Handle of the touch device from a previous TdiOpen call
  1442.  
  1443.  
  1444.  
  1445. OUTPUT
  1446. ______
  1447.  
  1448.  
  1449.          rc (USHORT)
  1450.          Return code in register AX
  1451.  
  1452.              0 - NO_ERROR
  1453.                  TDI_ERR_PARAMETERS_INVALID
  1454.                  TDI_ERR_UNKNOWN_COMMAND
  1455.                  TDI_ERR_GENERAL_FAILURE
  1456.  
  1457.  
  1458.  
  1459. Notes:
  1460.  
  1461. 1.  With the simple first value push harder mode,
  1462.     the selection detection flag set on when touch
  1463.     pressure increases past the push threshold.
  1464.     Selection detection flag reset off when touch
  1465.     pressure decreases below the push hysteresis
  1466.     threshold.
  1467.  
  1468. 2.  With the simple first value lift off mode, the
  1469.     selection detection flag is set and reset on
  1470.     consecutive data reports upon touch contact
  1471.     decreasing below the on screen threshold
  1472.     ('lift off').
  1473.  
  1474. 3.  The selection detection flag state can be read
  1475.     using TdiReadEventQueue and examining the
  1476.     status in TDIEVENTINFO.
  1477.  
  1478. 4.  For information on thresholds, see the
  1479.     associated functions TddSet/GetThresh.
  1480.  
  1481.  
  1482. TDIOPEN
  1483. _______
  1484.  
  1485. This call opens the touch device for the current
  1486. session.
  1487.  
  1488.  
  1489.          TdiOpen(DeviceHandle, rc)
  1490.  
  1491.  
  1492. INPUT PARAMETERS
  1493. ________________
  1494.  
  1495.  
  1496.  
  1497.          Device Handle (PHTDI)
  1498.          This is a pointer to HTDI into which the function will put
  1499.          the device handle
  1500.  
  1501.  
  1502.  
  1503. OUTPUT
  1504. ______
  1505.  
  1506.  
  1507.          rc (USHORT)
  1508.          Return code in register AX
  1509.  
  1510.              0 - NO_ERROR
  1511.                  TDI_ERR_PARAMETERS_INVALID
  1512.                  TDI_ERR_NOT_CALIBRATED
  1513.                  TDI_ERR_UNKNOWN_COMMAND
  1514.                  TDI_ERR_GENERAL_FAILURE
  1515.  
  1516.  
  1517.  
  1518. Notes:
  1519.  
  1520. 1.  An open will reset the touch screen parameters
  1521.     settable via the TdiSetxxx calls to the
  1522.     default values.  An exception is mouse
  1523.     emulation which will be turned off regardless
  1524.     of the emulation state in the screen group
  1525.     before the TdiOpen call was made.
  1526.  
  1527. 2.  This call will fail if the touch display has
  1528.     not been calibrated.
  1529.  
  1530.  
  1531. TDIREADEVENTQUEUE
  1532. _________________
  1533.  
  1534. This function reads an event from the touch
  1535. display device driver FIFO event queue and places
  1536. it in a structure provided by the application.
  1537.  
  1538.  
  1539.          TdiReadEventQueue(EventInfo, ReadType, DeviceHandle, rc)
  1540.  
  1541.  
  1542. INPUT PARAMETERS
  1543. ________________
  1544.  
  1545.  
  1546.          EventInfo (PTDIEVENTINFO)
  1547.          This is a pointer to a structure of type TDIEVENTINFO into
  1548.          which the function will place the event data.
  1549.  
  1550.  
  1551.  
  1552.          XYZ DATA
  1553.  
  1554.            Offset      Type         Description
  1555.  
  1556.            0H          USHORT       cEvents
  1557.            2H          USHORT       TouState
  1558.            4H          ULONG        EventTime  (event time stamp in ms)
  1559.            8H          USHORT       X Value
  1560.            AH          USHORT       Y Value
  1561.            CH          USHORT       Z Value
  1562.  
  1563.  
  1564.            cEvents
  1565.            Gives a count of the remaining number
  1566.              of events in the event queue
  1567.            after this event has been read.
  1568.  
  1569.  
  1570.            TouState
  1571.            Represents the state of the touch display at the
  1572.            time the event is reported.
  1573.  
  1574.           BIT      Description
  1575.  
  1576.            0         1 = On screen event (On Screen status set)
  1577.            1         1 = Touch Down event (On Screen status clear to set)
  1578.            2         1 = Lift Off event (On Screen status set to clear)
  1579.            3         1 = Selection detection flag set event
  1580.            4         1 = Selection Detection flag clear to set event
  1581.            5         1 = Selection Detection flag set to clear event
  1582.            6-F       reserved
  1583.  
  1584.  
  1585.  
  1586.          Read Type (PUSHORT)
  1587.          This is a pointer to a structure of type USHORT which indicates
  1588.          the action to take when the function is issued and the touch
  1589.          event queue is empty:
  1590.  
  1591.           0 = Return NULL EventInfo if data not available (NO WAIT)
  1592.           1 = WAIT for data on empty queue.
  1593.           2 = PEEK return event info but do not
  1594.               remove event from event queue
  1595.  
  1596.  
  1597.          Device Handle (HTDI)
  1598.          Handle of the touch device from a previous TdiOpen call
  1599.  
  1600.  
  1601.  
  1602. OUTPUT
  1603. ______
  1604.  
  1605.  
  1606.          rc (USHORT)
  1607.          Return code in register AX
  1608.  
  1609.              0 - NO_ERROR
  1610.                  TDI_ERR_PARAMETERS_INVALID
  1611.                  TDI_ERR_UNKNOWN_COMMAND
  1612.                  TDI_ERR_GENERAL_FAILURE
  1613.  
  1614.  
  1615.  
  1616.  
  1617. TDISETCOORDSYS
  1618. ______________
  1619.  
  1620. This function sets the current coordinate
  1621. reporting range and hysteresis used in x,y
  1622. reports.
  1623.  
  1624.  
  1625.          TdiSetCoordSys(CoordSys, DeviceHandle, rc)
  1626.  
  1627.  
  1628. INPUT PARAMETERS
  1629. ________________
  1630.  
  1631.  
  1632.          CoordSys   (PTDICOORDSYS)
  1633.          This is a pointer to a structure of type TDICOORDSYS which
  1634.          contains the coordinate system required:
  1635.  
  1636.          Offset      Type         Description
  1637.  
  1638.          0H          USHORT       X minimum value
  1639.          2H          USHORT       X maximum value
  1640.          4H          USHORT       Y minimum value
  1641.          6H          USHORT       Y maximum value
  1642.          8H          USHORT       Z minimum value
  1643.          AH          USHORT       Z maximum value
  1644.          CH          USHORT       X hysteresis value * 1000
  1645.          EH          USHORT       Y hysteresis value * 1000
  1646.  
  1647.  
  1648.  
  1649.          Device Handle (HTDI)
  1650.          Handle of the touch device from a previous TdiOpen call
  1651.  
  1652.  
  1653.  
  1654. OUTPUT
  1655. ______
  1656.  
  1657.  
  1658.          rc (USHORT)
  1659.          Return code in register AX
  1660.  
  1661.              0 - NO_ERROR
  1662.                  TDI_ERR_PARAMETERS_INVALID
  1663.                  TDI_ERR_UNKNOWN_COMMAND
  1664.                  TDI_ERR_GENERAL_FAILURE
  1665.  
  1666.  
  1667.  
  1668. Notes:
  1669.  
  1670. 1.  Hysteresis is the amount, expressed in
  1671.     coordinate report units multiplied by 1000, by
  1672.     which a touch contact must cross the border
  1673.     between adjacent coordinate cells before a
  1674.     change in coordinate report is registered.
  1675.  
  1676. 2.  This is to prevent reports flickering between
  1677.     two values when a touch contact point lies on
  1678.     the border of adjacent coordinate cells.
  1679.  
  1680. 3.  A default hysteresis of 0.5 coordinate units
  1681.     (reported value of 500 using the
  1682.     TdiGetCoordSys() call) is used.
  1683.  
  1684. 4.  X,Y and Z values can be in the range -32768 to
  1685.     +32767.
  1686.  
  1687. 5.  Hysteresis values are unsigned integers in the
  1688.     range 0 to 65535
  1689.  
  1690. 6.  Hysteresis values are expressed in terms of
  1691.     the required hysteresis value, in coordinate
  1692.     system units, multiplied by 1000.
  1693.  
  1694. 7.  Thus a value of 500 indicated a hysteresis of
  1695.     500/1000 = 0.5 screen units.  The maximum
  1696.     hysteresis that may be set is therefore 65.535
  1697.     screen units, corresponding to the maximum
  1698.     permitted value 65535.
  1699.  
  1700.  
  1701. TDISETEMULSTATE
  1702. _______________
  1703.  
  1704. This function enables or disables mouse emulation.
  1705.  
  1706.  
  1707.          TdiSetEmulState (EmulState, DeviceHandle, rc)
  1708.  
  1709.  
  1710. INPUT PARAMETERS
  1711. ________________
  1712.  
  1713.  
  1714.          EmulState (PUSHORT)
  1715.          This is a pointer to a structure of type USHORT in which the
  1716.          function returns the mouse emulation state:
  1717.  
  1718.          Bit      Description
  1719.  
  1720.           0       Mouse emulation state
  1721.                   =0 = Emulation off, =1 = Emulation on
  1722.           1-F     Reserved (=0)
  1723.  
  1724.  
  1725.          Device Handle (HTDI)
  1726.          Handle of the touch device from a previous TdiOpen call
  1727.  
  1728.  
  1729.  
  1730. OUTPUT
  1731. ______
  1732.  
  1733.  
  1734.          rc (USHORT)
  1735.          Return code in register AX
  1736.  
  1737.              0 - NO_ERROR
  1738.                  TDI_ERR_PARAMETERS_INVALID
  1739.                  TDI_ERR_UNKNOWN_COMMAND
  1740.                  TDI_ERR_GENERAL_FAILURE
  1741.  
  1742.  
  1743.  
  1744. Notes:
  1745.  
  1746. 1.  Under Presentation Manager any program which
  1747.     opens the Touch Display device (TdiOpen)
  1748.     disables mouse emulation for the whole of the
  1749.     Presentation Manager session.  Mouse emulation
  1750.     can be enabled while the touch device is open
  1751.     using TdiSetEmulState(), whence touch data
  1752.     becomes available both as emulated mouse data
  1753.     as well as touch data.
  1754.  
  1755.  
  1756. TDISETEVENTMASK
  1757. _______________
  1758.  
  1759. This function assigns a new event mask to the
  1760. current touch display device driver.  The mask
  1761. controls which data events from the touch display
  1762. are inserted into the event queue (see also
  1763. "TdiReadEventQueue").
  1764.  
  1765.  
  1766.          TdiSetEventMask(EventMask, DeviceHandle, rc)
  1767.  
  1768.  
  1769. INPUT PARAMETERS
  1770. ________________
  1771.  
  1772.  
  1773.          EventMask (USHORT)
  1774.          This is a structure of type USHORT in which the caller supplies
  1775.          the required event mask:
  1776.  
  1777.   Bit          Description
  1778.  
  1779.     0         1 = report On screen events (On Screen status set)
  1780.     1         1 = report Touch Down events (On Screen status clear to set)
  1781.     2         1 = report Lift Off events (On Screen status set to clear)
  1782.     3         1 = report Selection detection flag set events
  1783.     4         1 = report Selection Detection flag clear to set events
  1784.     5         1 = report Selection Detection flag set to clear events
  1785.     6-F       reserved
  1786.  
  1787.  
  1788.          Device Handle (HTDI)
  1789.          Handle of the touch device from a previous TdiOpen call
  1790.  
  1791.  
  1792.  
  1793. OUTPUT
  1794. ______
  1795.  
  1796.  
  1797.          rc (USHORT)
  1798.          Return code in register AX
  1799.  
  1800.              0 - NO_ERROR
  1801.                  TDI_ERR_PARAMETERS_INVALID
  1802.                  TDI_ERR_UNKNOWN_COMMAND
  1803.                  TDI_ERR_GENERAL_FAILURE
  1804.  
  1805.  
  1806.  
  1807.  
  1808. TDISETQUEUESIZE
  1809. _______________
  1810.  
  1811. This function allows the maximum number of queued
  1812. elements to be altered (subject to the limit set
  1813. from the CONFIG.SYS QSIZE= parameter).
  1814.  
  1815.  
  1816.          TdiSetQueueSize(QueSize, DeviceHandle, rc)
  1817.  
  1818.  
  1819. INPUT PARAMETERS
  1820. ________________
  1821.  
  1822.  
  1823.          QueSize (USHORT)
  1824.          This is a pointer to USHORT which contains the required maximum
  1825.          number of queued elements in the Touch Device event queue:
  1826.  
  1827.          Offset      Type         Description
  1828.  
  1829.          0H          USHORT       Maximum number of elements in
  1830.                                   event queue
  1831.  
  1832.  
  1833.  
  1834.          Device Handle (HTDI)
  1835.          Handle of the touch device from a previous TdiOpen call
  1836.  
  1837.  
  1838.  
  1839. OUTPUT
  1840. ______
  1841.  
  1842.  
  1843.          rc (USHORT)
  1844.          Return code in register AX
  1845.  
  1846.              0 - NO_ERROR
  1847.                  TDI_ERR_PARAMETERS_INVALID
  1848.                  TDI_ERR_UNKNOWN_COMMAND
  1849.                  TDI_ERR_GENERAL_FAILURE
  1850.  
  1851.  
  1852.  
  1853. Notes:
  1854.  
  1855. 1.  This function will return an error if an
  1856.     attempt is made to set the current number of
  1857.     event queue elements to greater than the
  1858.     maximum size set in the CONFIG.SYS QSIZE=
  1859.     parameter.
  1860.  
  1861. 2.  If queue size input is set to zero, this will
  1862.     force the QSIZE= parameter value to be used as
  1863.     the current queue size.  The minimum queue
  1864.     size which may be set using this function is
  1865.     therefore 1.
  1866.  
  1867.  
  1868. TDISETSELECTMETHOD
  1869. __________________
  1870.  
  1871. This function sets the selection detection flag
  1872. set/reset mechanism.
  1873.  
  1874.  
  1875.          TdiSetSelectMethod(SelectMech, DeviceHandle, rc)
  1876.  
  1877.  
  1878. INPUT PARAMETERS
  1879. ________________
  1880.  
  1881.  
  1882.          Selectmech (PTDISELMECH)
  1883.          This is a pointer to a structure of type TDISELMECH which
  1884.          contains the required selection detection
  1885.          flag set/reset mechanism.
  1886.  
  1887.  
  1888.          Offset      Type         Description
  1889.  
  1890.          0H          USHORT       Selection Type
  1891.                                    Bit 0
  1892.                                       0 = Push harder (default)
  1893.                                       1 = Lift Off
  1894.                                    Bit 1
  1895.                                       0 = First value taken
  1896.                                       1 = Single touch algorithm active
  1897.                                    Bit 2
  1898.                                       0 = First value taken
  1899.                                       1 = Stable region algorithm active
  1900.                                    Bit 3 - F
  1901.                                       0 = Reserved
  1902.  
  1903.          2H          USHORT        Number of stable points
  1904.                                     0 = default
  1905.                                     n = # of stable points
  1906.  
  1907.          4H          USHORT        Tolerance value
  1908.                                     0 = default
  1909.                                     n = tolerance in pixels
  1910.  
  1911.          6H          USHORT        Stack length
  1912.                                     0 = default
  1913.                                     n = length in samples ( 0 < n < 60 )
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.          Device Handle (HTDI)
  1920.          Handle of the touch device from a previous TdiOpen call
  1921.  
  1922.  
  1923.  
  1924. OUTPUT
  1925. ______
  1926.  
  1927.  
  1928.          rc (USHORT)
  1929.          Return code in register AX
  1930.  
  1931.              0 - NO_ERROR
  1932.                  TDI_ERR_PARAMETERS_INVALID
  1933.                  TDI_ERR_UNKNOWN_COMMAND
  1934.                  TDI_ERR_GENERAL_FAILURE
  1935.  
  1936.  
  1937.  
  1938. Notes:
  1939.  
  1940. 1.  With the simple first value push harder mode,
  1941.     the selection detection flag is set (=1) when
  1942.     touch force rises above the push threshold.
  1943.     Selection detection flag is reset (=0) when
  1944.     touch pressure falls below the push hysteresis
  1945.     threshold.
  1946.  
  1947. 2.  With the simple first value lift off mode, the
  1948.     selection detection flag is set and reset in
  1949.     consecutive data reports upon touch contact
  1950.     force falling below the on screen threshold
  1951.     ('lift off').
  1952.  
  1953.  
  1954. 3.  The selection detection flag state can be read
  1955.     using TdiReadEventQueue and examining the
  1956.     status in TDIEVENTINFO.
  1957.  
  1958.  
  1959. TDIXXX RETURN CODES
  1960. ___________________
  1961.  
  1962.  
  1963.              0 - NO_ERROR
  1964.                  TDI_ERR_NOT_CALIBRATED
  1965.                  TDI_ERR_PARAMETERS_INVALID
  1966.                  TDI_ERR_UNKNOWN_COMMAND
  1967.                  TDI_ERR_GENERAL_FAILURE
  1968.  
  1969.  
  1970. Apart from the not calibrated return code, these
  1971. are aliases of the OS/2 DosDevIOCtl return codes.
  1972.  
  1973.  
  1974. OS/2 DEVICE DEPENDENT API
  1975. _________________________
  1976.  
  1977. The following table shows the new TDDXXX API which
  1978. will not be exposed to new applications, being
  1979. used mainly by the calibration utility (requires
  1980. access to raw data and download calibration
  1981. constant functions) and the Touch Control Panel
  1982. (to set hardware dependent features such as touch
  1983. thresholds, filters etc.):
  1984.  
  1985.  
  1986.          TDDClose
  1987.          TDDDldCalibConsts
  1988.          TDDGetCalibConsts
  1989.          TDDGetClickLockData
  1990.          TDDGetEmulXYOffset
  1991.          TDDGetFilter
  1992.          TDDGetRepRate
  1993.          TDDGetThresh
  1994.          TDDOpen
  1995.          TDDReadData
  1996.          TDDReadMem
  1997.          TDDSetClickLockData
  1998.          TDDSetEmulXYOffset
  1999.          TDDSetFilter
  2000.          TDDSetMode
  2001.          TDDSetRepRate
  2002.          TDDSetThresh
  2003.          TDDWriteMem
  2004.  
  2005.  
  2006. This interface is not intended to be exposed to
  2007. the outside world, rather as just a convenient
  2008. means for the Touch Control Panel to access the
  2009. hardware without using direct DosDevIOCtl calls
  2010.  
  2011.  
  2012. TOUXXX API COMPATIBILITY
  2013. ________________________
  2014.  
  2015. For completeness, the following table gives the
  2016. complete API calls, including those provided for
  2017. compatibility (but not exposed as part of the new
  2018. API), and those which were never originally
  2019. exposed and were part of the TouXXX API, which
  2020. will be moved to a new device dependent TDDXXX API
  2021. (also not exposed).
  2022.  
  2023.  
  2024.          Device Independent                 Device Dependent
  2025.  
  2026.          TouClose                           TDDClose
  2027.          TouFlushQue                        TDDGetCalibConsts
  2028.        * TouGetCoordOrg                     TDDDldCalibConsts
  2029.        * TouGetCoordSys                     TDDReadMem
  2030.        - TouGetDevStatus                    TDDWriteMem
  2031.          TouGetEmulOnOff
  2032.          TouGetEventMask
  2033.          TouGetNumQueEl                  TDDReadData (raw/xyz for calib)
  2034.          TouGetSelectMech
  2035.          TouOpen                        TDDOpen  (only one handle, cuts
  2036.          TouReadEventQue                             touch data supply to
  2037.          TouResetEmulState                          TOUCH.SYS + MOUSE.SYS)
  2038.        * TouSetCoordOrg
  2039.        * TouSetCoordSys                     TDDSetMode  (raw/xyz)
  2040.          TouSetEmulOnOff
  2041.          TouSetEventMask
  2042.          TouSetNumQueEl
  2043.          TouSetSelectMech
  2044.  
  2045.        # TouGetClickLockData                TDDGetClickLockData
  2046.        # TouGetFilter                       TDDGetFilter
  2047.        # TouGetRepRate                      TDDGetRepRate
  2048.        # TouGetThresh                       TDDGetThresh
  2049.        # TouSetClickLockData                TDDSetClickLockData
  2050.        # TouSetFilter                       TDDSetFilter
  2051.        # TouSetRepRate                      TDDSetRepRate
  2052.      * # TouSetThresh                       TDDSetThresh
  2053.        # TouQueryParms
  2054.        # TouSelectParms
  2055.  
  2056.        # TouGetXYOffset                     TDDGetEmulXYOffset
  2057.        # TouSetXYOffset                     TDDSetEmulXYOffset
  2058.  
  2059.  
  2060.  
  2061.    Notes on new API:
  2062.  
  2063.        Only device dependent functions have effect on hardware state.
  2064.  
  2065.    Key:
  2066.  
  2067.      # indicates provided for compatibility only.  Not virtualised
  2068.        and therefore have no effect on driver or hardware state.
  2069.        For each function not virtualised there is a companion (new)
  2070.        TDDxxx function to perform this device unique/dependent
  2071.        function.  Effects of these functions will be session wide.
  2072.  
  2073.      * indicates function virtualised in driver a with no effect
  2074.        on hardware state
  2075.  
  2076.        For thresholds the on screen threshold can be virtualised
  2077.        only to a limited degree, namely that the virtualisation
  2078.        may not be completely transparent to the end user (eg if
  2079.        a low on screen  threshold is set by the application the
  2080.        user may not 'feel' the difference.)
  2081.  
  2082.      - indicates this function has been removed altogether.
  2083.  
  2084.  
  2085.  
  2086. DOS DEVICE DEPENDENT API
  2087. ________________________
  2088.  
  2089. Data via the DOS touch INT7Fh API will only be
  2090. available to DOS programs running full screen not
  2091. in a PM window.  All other functions not involving
  2092. data will operate correctly.
  2093.  
  2094. Note that, however, if mouse emulation is turned
  2095. on in a DOS session, the application can then
  2096. receive touch input in the form of emulated mouse
  2097. input when running in a DOS window under PM.
  2098.  
  2099. --------------------------------------------------------------------
  2100.  
  2101.  Software Interrupt INT 7Fh
  2102.  
  2103.  On Entry:
  2104.            AX = ABCDH
  2105.            BX = 0H
  2106.  
  2107.  On Exit:
  2108.            (CY) - 0 operation successful
  2109.                 - 1 operation unsuccessful
  2110.            ES:BX points to a table of far call entry points:
  2111.  
  2112.            AX = Total number of functions available.
  2113.  
  2114.  Offset    Function                        Compatibility (not exposed)
  2115.  
  2116.     00H  - Installed flag and Reset
  2117.     04H  - Mouse emulation Reset
  2118.     08H  - Mouse emulation off/on
  2119. *   0CH  - Set coordinate system
  2120. *   10H  - Set coordinate origin
  2121.     14H  -                                 Set thresholds
  2122.     18H  - Set selection mechanism
  2123.     1CH  -                                 Set data report rate
  2124.     20H  - Set data block mask
  2125.     24H  - Get touch down information
  2126.     28H  - Get lift off information
  2127.     2CH  - Get selection turned on information
  2128.     30H  - Get selection turned off information
  2129.     34H  - Get current position and status
  2130.     38H  - Set User-defined Subroutine
  2131.     3CH  - Swap User-defined Subroutine
  2132.     40H  - Set filter type and cut off frequency
  2133.     44H  - Query Save State storage requirements
  2134.     48H  - Save Driver State
  2135.     4CH  - Restore Driver State
  2136.     50H  - Get Mouse emulation state
  2137.     54H  - Get Mouse emulation off/on
  2138. *   58H  - Get coordinate system
  2139. *   5CH  - Get coordinate origin
  2140.     60H  - Get thresholds
  2141.     64H  - Get selection mechanism
  2142.     68H  - Get data report rate
  2143.     6CH  - Get data block mask
  2144.     70H  - Get filter type and cut off frequenc                                 y
  2145.     74H  - Get driver/microcode level
  2146.     78H  - Get click lock data
  2147.     7CH  - Set click lock data
  2148.  
  2149.  
  2150. ------------------------------------------------------------------------
  2151. Figure 2. INT 7FH, AX=ABCDH, BX=0H.  touch display interface functions
  2152.  
  2153. TOUCH CONTROL PANEL
  2154. ___________________
  2155.  
  2156. A Presentation Manager Control Panel type program
  2157. will provide the primary point of access to device
  2158. dependent features, as well as some device
  2159. independent ones.  These are for IBM PS/2 8516
  2160. Touch Display:
  2161.  
  2162. o   Mouse emulation only
  2163.  
  2164.     This affects the PM desktop session as well as
  2165.     the OS/2 full screen sessions.  The DOS
  2166.     sessions have individual mouse emulation
  2167.     control (via INT7Fh API or using the
  2168.     DEVUTIL.EXE DOS developers utility.
  2169.  
  2170.     1.  Mouse pointer XY offset
  2171.  
  2172.     2.  Mouse emulation button down sound/beep
  2173.         feedback on|off control
  2174.  
  2175.     3.  Mouse emulation Button/Click locking
  2176.         parameters
  2177.  
  2178.     4.  Mouse emulation on|off control
  2179.  
  2180. o   Full touch mode and mouse emulation mode
  2181.  
  2182.     These settings affect the touch device as a
  2183.     whole and therefore affect all sessions, be
  2184.     they PM, OS/2 full screen or DOS full screen.
  2185.  
  2186.     1.  Touch force thresholds
  2187.  
  2188.             On screen threshold
  2189.             Button down (selection on in full
  2190.             touch) threshold
  2191.             Button up (selection off in full
  2192.             touch) threshold
  2193.  
  2194.     2.  Filter type/ cutoff frequency
  2195.  
  2196.     3.  Touch data packet report rate
  2197.  
  2198. It should be noted that only one set of values for
  2199. hardware dependent parameters is in operation
  2200. between mouse emulation mode and full touch mode,
  2201. as well as across all sessions.  This is to ensure
  2202. that there is one consistent set of parameters
  2203. active for the touch device, regardless of which
  2204. session and under which mode it may be used.
  2205.  
  2206. (This is to be contrasted with the situation with
  2207. the OS/2 1.x support, where different settings
  2208. could be active for mouse emulation mode and full
  2209. touch mode for each session.)
  2210.  
  2211. For this reason, the distinction between mouse
  2212. emulation parameters and full touch parameters can
  2213. be removed, with no need in the control panel to
  2214. distinguish, for example, between the On screen
  2215. threshold, or the filter type, set for full touch
  2216. mode and that set for mouse emulation mode.
  2217.  
  2218.  
  2219.  
  2220. Inter-Device Communication Interfaces (IDC's)
  2221.  
  2222. DEVICE INDEPENDENT TO DEVICE DEPENDENT
  2223. ______________________________________
  2224.  
  2225. The IDC provided by the device independent device
  2226. driver consists of the following functions:
  2227.  
  2228. o   Process packet
  2229.  
  2230. o   Disable Support
  2231.  
  2232.  
  2233. PROCESS PACKET
  2234.  
  2235. This function is called by the device dependent
  2236. driver when it has completed receiving and
  2237. formatting touch device data into the shared data
  2238. buffer address, so that the data may then be
  2239. processed by the device independent driver.
  2240.  
  2241. Input:
  2242.  
  2243.     AX= Function Request code =0001H
  2244.     SI= shared data buffer offset
  2245.     DS= device independent driver's DS value
  2246.     ES= device dependent driver's DS value
  2247.     (caller)
  2248.     BX,CX,DX, and DI register contents are
  2249.     undefined
  2250.  
  2251. Output:
  2252.  
  2253.     AX= Error return code (if carry set, undefined
  2254.     if carry clear)
  2255.     DS= device independent driver's DS value
  2256.     ES= device dependent driver's DS value
  2257.     (caller)
  2258.     BX,CX,DX,SI and DI register contents are
  2259.     undefined
  2260.  
  2261.  
  2262. DISABLE SUPPORT
  2263.  
  2264. This function is used by the device dependent
  2265. device driver to inform the device independent
  2266. driver that it has received a Deinstall request
  2267. and wishes to release its system resources.  The
  2268. device independent driver cannot deinstall itself
  2269. at this point, but it can disable the API
  2270. interfaces.
  2271.  
  2272. Input:
  2273.  
  2274.     AX= Function Request code =0002H
  2275.     DS= device independent driver's DS value
  2276.     ES= device dependent driver's DS value
  2277.     (caller)
  2278.     BX,CX,DX,SI and DI register contents are
  2279.     undefined
  2280.  
  2281. Output:
  2282.  
  2283.     AX= Error return code (if carry set, undefined
  2284.     if carry clear)
  2285.     DS= device independent driver's DS value
  2286.     ES= device dependent driver's DS value
  2287.     (caller)
  2288.     BX,CX,DX,SI and DI register contents are
  2289.     undefined
  2290.  
  2291.  
  2292. DEVICE DEPENDENT TO DEVICE INDEPENDENT
  2293. ______________________________________
  2294.  
  2295. The IDC provided by the mouse component of the
  2296. device dependent device driver is identical to
  2297. that provided by a PS/2 mouse device dependent
  2298. driver, with 2 exceptions: Enable and Disable
  2299. device functions do not enable/disable the device
  2300. at the IRQ level (which would cause the touch
  2301. device to be simultaneously enabled/disabled), but
  2302. simply stop/start reporting of data to the device
  2303. independent driver.
  2304.  
  2305. The IDC provided by the touch component of the
  2306. device dependent device driver consists of the
  2307. following functions:
  2308.  
  2309. o   Query Configuration
  2310.  
  2311. o   Enable Read
  2312.  
  2313. o   Disable Write
  2314.  
  2315. o   Enable Device
  2316.  
  2317. o   Disable Device
  2318.  
  2319. o   Set Emulation State
  2320.  
  2321.  
  2322. QUERY CONFIGURATION
  2323.  
  2324. Input:
  2325.  
  2326.     AX= Function Request code =0001H
  2327.     DI= config data buffer offset
  2328.     DS= device dependent driver's DS value
  2329.     ES= device independent driver's DS value
  2330.     (caller)
  2331.     BX,CX,DX, and SI register contents are
  2332.     undefined
  2333.  
  2334. ES:DI points to a data structure which is filled
  2335. in by the device dependent driver to convey
  2336. configuration information back to the device
  2337. independent driver, according to the following
  2338. format:
  2339.  
  2340.  
  2341.           config_data struc
  2342.  
  2343.                       length    dw ?  ; length (inclusive) of structure in bytes
  2344.                       irq_num   db ?  ; interrupt request level for device
  2345.                       mou_stat  dw ?  ; mouse device status flags
  2346.                                       ; bit 0 =1 Physical PS/2 mouse attached
  2347.                                       ; bit 1 =1 Device independent driver attached
  2348.                                       ; bit 2 =1 Protected mode emulation enabled
  2349.                                       ; bit 3 =1 Real mode emulation enabled
  2350.                       tou_stat  dw ?  ; touch device status flags
  2351.                                       ; bit 0 =1 Touch device calibrated
  2352.  
  2353.           config_data ends
  2354.  
  2355.  
  2356.  
  2357. Output:
  2358.  
  2359.     AX= Error return code (if carry set, undefined
  2360.     if carry clear)
  2361.     DI= config data buffer offset
  2362.     ES= device independent driver's DS value
  2363.     (caller)
  2364.     BX,CX,DX,SI and DS register contents are
  2365.     undefined
  2366.  
  2367.  
  2368. ENABLE READ
  2369.  
  2370. This function is issued by the device independent
  2371. driver to indicate that data packet processing has
  2372. been set up and data transfer may begin.
  2373.  
  2374. Input:
  2375.  
  2376.     AX= Function Request code =0002H
  2377.     DI= shared interrupt data buffer offset
  2378.     DS= device dependent driver's DS value
  2379.     ES= device independent driver's DS value
  2380.     (caller)
  2381.     BX,CX,DX, and SI register contents are
  2382.     undefined
  2383.  
  2384. ES:DI points to the interrupt data packet
  2385. structure in which the called device driver will
  2386. write/return the touch data packet when a complete
  2387. packet has been accumulated.
  2388.  
  2389.  
  2390.           touch_data struc
  2391.  
  2392.                       status    dw ?  ; touch display status
  2393.                       x_coord   dw ?  ; x coordinate of touch
  2394.                       y_coord   dw ?  ; y coordinate of touch
  2395.                       z_coord   dw ?  ; z coordinate of touch
  2396.                       x_range   dw ?  ; Xmax - Xmin
  2397.                       y_range   dw ?  ; Ymax - Ymin
  2398.                       z_range   dw ?  ; Zmax - Zmin
  2399.  
  2400.           touch_data ends
  2401.  
  2402.  
  2403. Note:  X,Y,Z coordinates are reported in fixed
  2404. 4096x4096x255 coordinate space.  X increases left
  2405. to right, Y increases top to bottom.
  2406.  
  2407. Output:
  2408.  
  2409.     AX= Error return code (if carry set, undefined
  2410.     if carry clear)
  2411.     ES= device independent driver's DS value
  2412.     (caller)
  2413.     BX,CX,DX,SI,DI and DS register contents are
  2414.     undefined
  2415.  
  2416.  
  2417. DISABLE WRITE
  2418.  
  2419. This function is called by the device independent
  2420. driver to indicate that data packet processing is
  2421. no longer supported and that data transfers via
  2422. Process Packet should be stopped until a Enable
  2423. Read request is processed.  Following this call no
  2424. further references should be made to the shared
  2425. interrupt data buffer address previously provided
  2426. via the last Enable Read request.
  2427.  
  2428. Input:
  2429.  
  2430.     AX= Function Request code =0003H
  2431.     DS= device dependent driver's DS value
  2432.     ES= device independent driver's DS value
  2433.     (caller)
  2434.     BX,CX,DX,SI and DI register contents are
  2435.     undefined
  2436.  
  2437. Output:
  2438.  
  2439.     AX= Error return code (if carry set, undefined
  2440.     if carry clear)
  2441.     ES= device independent driver's DS value
  2442.     (caller)
  2443.     BX,CX,DX,SI,DI and DS register contents are
  2444.     undefined
  2445.  
  2446.  
  2447. ENABLE DEVICE
  2448.  
  2449. This function is used to enable the touch data
  2450. event reporting from the device dependent driver
  2451. to the device independent driver.  It does not
  2452. affect interrupt data processing at the IRQ level
  2453. (which is shared between PS/2 mouse and touch
  2454. devices), therefore mouse data event processing
  2455. and reporting is not affected.
  2456.  
  2457. Input:
  2458.  
  2459.     AX= Function Request code =0004H
  2460.     DS= device dependent driver's DS value
  2461.     ES= device independent driver's DS value
  2462.     (caller)
  2463.     BX,CX,DX,SI and DI register contents are
  2464.     undefined
  2465.  
  2466. Output:
  2467.  
  2468.     AX= Error return code (if carry set, undefined
  2469.     if carry clear)
  2470.     ES= device independent driver's DS value
  2471.     (caller)
  2472.     BX,CX,DX,SI,DI and DS register contents are
  2473.     undefined
  2474.  
  2475.  
  2476. DISABLE DEVICE
  2477.  
  2478. This function is used to disable the touch data
  2479. event reporting from the device dependent driver
  2480. to the device independent driver.  It does not
  2481. affect interrupt data processing at the IRQ level
  2482. (which is shared between PS/2 mouse and touch
  2483. devices), therefore mouse data event processing
  2484. and reporting is not affected.
  2485.  
  2486. Input:
  2487.  
  2488.     AX= Function Request code =0004H
  2489.     DS= device dependent driver's DS value
  2490.     ES= device independent driver's DS value
  2491.     (caller)
  2492.     BX,CX,DX,SI and DI register contents are
  2493.     undefined
  2494.  
  2495. Output:
  2496.  
  2497.     AX= Error return code (if carry set, undefined
  2498.     if carry clear)
  2499.     ES= device independent driver's DS value
  2500.     (caller)
  2501.     BX,CX,DX,SI,DI and DS register contents are
  2502.     undefined
  2503.  
  2504.  
  2505. SET EMULATION STATE
  2506.  
  2507. This function is used to control the way that
  2508. touch data packets are handled by the device
  2509. dependent driver.  When emulation mode is set to
  2510. off, touch data packets are only reported to the
  2511. touch device independent driver as direct x,y,z
  2512. data packets.  When mouse emulation mode is set to
  2513. absolute, the touch data packet is additionally
  2514. converted into a mouse data packet of absolute x,y
  2515. form, and reported to the mouse device independent
  2516. driver via its Process Packet Absolute IDC entry
  2517. point.  When mouse emulation mode is set to
  2518. relative, the touch data packet is additionally
  2519. converted into a mouse data packet of relative
  2520. dx,dy form, and reported to the mouse device
  2521. independent driver via its standard Process Packet
  2522. IDC entry point.
  2523.  
  2524. Input:
  2525.  
  2526.     AX= Function Request code =0006H
  2527.     BX= Emulation mode (0=off 1=absolute
  2528.     2=relative)
  2529.     DS= device dependent driver's DS value
  2530.     ES= device independent driver's DS value
  2531.     (caller)
  2532.     CX,DX,DI and SI register contents are
  2533.     undefined
  2534.  
  2535. Output:
  2536.  
  2537.     AX= Error return code (if carry set, undefined
  2538.     if carry clear)
  2539.     ES= device independent driver's DS value
  2540.     (caller)
  2541.     BX,CX,DX,DI,SI and DS register contents are
  2542.     undefined
  2543.  
  2544.  
  2545. PHYSICAL DEVICE DRIVER TO VIRTUAL DEVICE DRIVER
  2546. _______________________________________________
  2547.  
  2548. The primary function is to communicate touch data
  2549. packets to the virtual device driver.  Unlike the
  2550. virtual mouse driver, which can also receive mouse
  2551. data from the PM shell so that DOS windows receive
  2552. mouse data correctly adjusted for window size and
  2553. position, this is the only route for touch data
  2554. into the virtual device driver.  Because of the
  2555. lack of cooperative PM support in the way the
  2556. mouse gets data, DOS windows are unable to receive
  2557. touch data correctly adjusted for window size and
  2558. position.  Normally.  therefore, a VDM will only
  2559. receive touch data when it is running full screen
  2560. (ie non-PM foreground session).  In the PM
  2561. session, all touch data will be used to form
  2562. emulated mouse packets and reported to the
  2563. Physical Mouse Driver.  The Virtual Mouse Driver
  2564. will then receive emulated mouse data via the
  2565. normal PM shell route (or via Physical Driver
  2566. route if exclusive mouse access 'on').
  2567.  
  2568. However, by using the 'Exclusive touch access' DOS
  2569. property, a window can receive all touch data when
  2570. running in the PM session.  Since the data is in
  2571. the form of full screen coordinates, a DOS window
  2572. must effectively be run maximised (except for text
  2573. mode applications where maximising a window does
  2574. not cover the full screen) to run without
  2575. modification (else it would have to perform the
  2576. coordinate conversion itself, which is surely an
  2577. impossible task for a DOS program since it has no
  2578. knowledge of, or access to, window position/size
  2579. information.
  2580.  
  2581. The PDD is passed the VDD entry point as a
  2582. consequence of the VDD calling VDHOpenPDD with the
  2583. 16:16 address of VTEventProc as parameter.
  2584.  
  2585.  
  2586. VTEVENTPROC FUNCTION 1 : PROCESS PACKET/EVENT
  2587.  
  2588.   /***EP  VTEventProc - Process event packets from PDD.
  2589.    *
  2590.    *  ENTRY
  2591.    *      ulFunc == function code (VTDCMD_REPORT_EVENT)
  2592.    *      f16p1 -> MONREC
  2593.    *      f16p2 -  Not used.
  2594.    *
  2595.    *  EXIT
  2596.    *      None
  2597.    *
  2598.    *  USES
  2599.    *      32-bit small-model PASCAL calling/register conventions
  2600.    *
  2601.    *  CONTEXT
  2602.    *      Interrupt-time
  2603.    *
  2604.    *  PSEUDO-CODE
  2605.    *      if handle and pointer are valid and touch is enabled,
  2606.    *          add the event to the VDM's buffer.
  2607.    */
  2608.  
  2609.   VOID    VDDENTRY VTEventProc(ULONG ulFunc, F16PVOID f16p1, F16PVOID f16p2);
  2610.  
  2611. The MONREC pointer points to a structure as
  2612. detailed below:
  2613.  
  2614.   /***ET+ PTD-to-VTD communication structures
  2615.    *
  2616.    */
  2617.  
  2618.   typedef struct {                                // VTDCMD_REPORT_EVENT
  2619.           USHORT          Status;
  2620.           ULONG           TimeStamp;
  2621.           USHORT          x;
  2622.           USHORT          y;
  2623.           USHORT          z;
  2624.       } QEVENT, * PQEVENT, * * PPQEVENT;
  2625.  
  2626.   typedef struct {
  2627.               USHORT      SGId;
  2628.               QEVENT      QEvent;
  2629.       } MONREC, * PMONREC;
  2630.  
  2631.  
  2632. VIRTUAL DEVICE DRIVER TO PHYSICAL DEVICE DRIVER
  2633. _______________________________________________
  2634.  
  2635. The primary function of this interface is to
  2636. register the VDD with the PDD so that it can later
  2637. call it back with data, establish the
  2638. configuration set up (physical mouse attached or
  2639. not, touch display calibrated or not etc.), and
  2640. device control (emulation on/off, DOS property
  2641. 'exclusive access' on/off etc.
  2642.  
  2643. The functions supported are:
  2644.  
  2645. o   Register VDD
  2646.  
  2647. o   Query configuration
  2648.  
  2649. o   Set emulation state
  2650.  
  2651. o   Disable
  2652.  
  2653. o   Set exclusive access
  2654.  
  2655.  
  2656. FUNCTION 0 : REGISTER VDD - PDDREGISTER
  2657.  
  2658. Establishes the VDD entry point for the PDD to
  2659. call the VDD.
  2660.  
  2661.   /***LP  PddRegisterVdd - called when Vdd calls VDHOpenPDD()
  2662.    *
  2663.    * Input:
  2664.    *      USHORT  pIBuff.off      VDD's CS
  2665.    *      USHORT  pIBuff.sel      zero
  2666.    *      USHORT  pOBuff.off      low 16-bits of EIP for VDD entry point
  2667.    *      USHORT  pOBuff.sel      high 16-bits of EIP for VDD entry point
  2668.    *
  2669.    * Return:
  2670.    *      BOOL success (AX)
  2671.    *
  2672.    * Usage:
  2673.    *      Success = PddEntry( 0, VddEntrySelector, VddEntryOffset);
  2674.    *
  2675.    * Called from:
  2676.    *      PddEntry (seg3) via VdhOpenPdd()
  2677.    *
  2678.    */
  2679.  
  2680.   STATIC VDMFUNC PddRegisterVdd( PUSHORT pIBuff, PUSHORT pOBuff);
  2681.  
  2682.  
  2683. FUNCTION 1 : QUERY CONFIGURATION - PDDQUERYCONFIG
  2684.  
  2685. Returns device configuration information,
  2686. including device interrupt request (IRQ) level,
  2687. mouse status (physical mouse present, MOUSE.SYS
  2688. driver attached and emulation state) and touch
  2689. status (calibrated or not).
  2690.  
  2691.   /***LP  PddQueryConfig - copy device config data to a Vdd 16:16 ptr
  2692.    *
  2693.    * Input:
  2694.    *      None
  2695.    *
  2696.    * Return:
  2697.    *      Configuration data:
  2698.    *              USHORT  size = 7
  2699.    *              UCHAR   irq
  2700.    *              USHORT  mouse status
  2701.    *              USHORT  touch status
  2702.    *      BOOL success (AX)
  2703.    *
  2704.    * Usage:
  2705.    *      Success = PddEntry( 1, NULL, &ParmsAddr);
  2706.    *
  2707.    * Called from:
  2708.    *      PddEntry (seg3) [QueryType(&TouHardware)]
  2709.    */
  2710.  
  2711.   STATIC VDMFUNC PddQueryConfig( PUSHORT pOBuff);
  2712.  
  2713.  
  2714. FUNCTION 2 : SET EMULATION STATE - PDDSETEMUL
  2715.  
  2716. Used to switch mouse emulation in the DOS virtual
  2717. machine off or on (relative/glass mouse or
  2718. absolute).
  2719.  
  2720.   /***LP  PddSetEmul - set emulation state
  2721.    *
  2722.    * Input:
  2723.    *      Emulation data:
  2724.    *              USHORT  size = 3
  2725.    *              UCHAR   emul state (0 - off, 1 - absolute, 2 - glass)
  2726.    *
  2727.    * Return:
  2728.    *      BOOL success (AX)
  2729.    *
  2730.    * Usage:
  2731.    *      Success = PddEntry( 2, &DataAddr, NULL);
  2732.    *
  2733.    * Called from:
  2734.    *      PddEntry (seg3)
  2735.    */
  2736.  
  2737.   STATIC VDMFUNC PddSetEmul( PUSHORT pIBuff);
  2738.  
  2739.  
  2740. FUNCTION 3 : DISABLE - PDDDISABLE
  2741.  
  2742.   /***LP  PddDisable -
  2743.    *
  2744.    * Input:
  2745.    *      None
  2746.    *
  2747.    * Return:
  2748.    *      BOOL success (AX)
  2749.    *
  2750.    * Usage:
  2751.    *      Success = PddEntry( 3, NULL, NULL);
  2752.    *
  2753.    * Called from:
  2754.    *      PddEntry (seg3)
  2755.    */
  2756.  
  2757.   STATIC VDMFUNC PddDisable(VOID);
  2758.  
  2759.  
  2760. FUNCTION 4 : SET EXCLUSIVE ACCESS ON/OFF -
  2761. PDDSETEXCLACC
  2762.  
  2763. Allows a DOS window to receive full screen touch
  2764. data.  (valid for the PM session only).  Mouse
  2765. emulation is effectively turned off when exclusive
  2766. access in on.
  2767.  
  2768.   /***LP  PddSetExclAcc - set exclusive access on/off
  2769.    *
  2770.    * Input:
  2771.    *      Exclusive Access Data:
  2772.    *              USHORT  size = 3
  2773.    *              UCHAR   exclusive access flag (0 - off, 1 - on)
  2774.    *
  2775.    * Return:
  2776.    *      BOOL success (AX)
  2777.    *
  2778.    * Usage:
  2779.    *      Success = PddEntry( 4, &DataAddr, NULL);
  2780.    *
  2781.    * Called from:
  2782.    *      PddEntry (seg3)
  2783.    */
  2784.  
  2785.   STATIC VDMFUNC PddSetExclAcc( PUSHORT pIBuff);
  2786.  
  2787.  
  2788. Category 129 Touch Device Driver IOCtl Commands
  2789.  
  2790. All touch device driver IOCtl commands share
  2791. Category 129, distinguished by the device name
  2792. used in the device open (TOUCH$ for the device
  2793. independent and PDITOU$ for the device dependent
  2794. driver).
  2795.  
  2796.  
  2797. SUMMARY: DEVICE DEPENDENT DRIVER
  2798. ________________________________
  2799.  
  2800. +------------------------------------------------+
  2801. | Table 1.  Category 129 PDITOU$ Device IOCtl    |
  2802. |          Commands                              |
  2803. +-------+----------------------------------------+
  2804. | 50h   | Semaphore Get                          |
  2805. +-------+----------------------------------------+
  2806. | 51h   | Semaphore Release                      |
  2807. +-------+----------------------------------------+
  2808. | 52h   | Set Calibration Constants              |
  2809. +-------+----------------------------------------+
  2810. | 53h   | Read Data                              |
  2811. +-------+----------------------------------------+
  2812. | 54h   | Set Mode                               |
  2813. +-------+----------------------------------------+
  2814. | 55h   | Set Click Locking Parameters           |
  2815. +-------+----------------------------------------+
  2816. | 56h   | Set Thresholds                         |
  2817. +-------+----------------------------------------+
  2818. | 57h   | Set XY Offset                          |
  2819. +-------+----------------------------------------+
  2820. | 58h   | Set Report Rate                        |
  2821. +-------+----------------------------------------+
  2822. | 59h   | Set Low Pass Filter                    |
  2823. +-------+----------------------------------------+
  2824. | 5Ah   | Write Memory                           |
  2825. +-------+----------------------------------------+
  2826. | 5B -  | Reserved                               |
  2827. | 5Fh   |                                        |
  2828. +-------+----------------------------------------+
  2829. | 60H   | Get Calibration Constants              |
  2830. +-------+----------------------------------------+
  2831. | 61H   | Get Data Mode                          |
  2832. +-------+----------------------------------------+
  2833. | 62H   | Get Click Lock Parameters              |
  2834. +-------+----------------------------------------+
  2835. | 63H   | Get Touch Thresholds                   |
  2836. +-------+----------------------------------------+
  2837. | 64H   | Get Emulation XY Offset                |
  2838. +-------+----------------------------------------+
  2839. | 65H   | Get Data Report Rate                   |
  2840. +-------+----------------------------------------+
  2841. | 66H   | Get Low Pass Filter                    |
  2842. +-------+----------------------------------------+
  2843. | 67H   | Read Memory Location                   |
  2844. +-------+----------------------------------------+
  2845.  
  2846.  
  2847. CATEGORY 129 - FUNCTION 50H - RESERVED
  2848. ______________________________________
  2849.  
  2850. Currently performs no function
  2851.  
  2852.  
  2853. CATEGORY 129 - FUNCTION 51H - RESERVED
  2854. ______________________________________
  2855.  
  2856. Currently performs no function
  2857.  
  2858.  
  2859. CATEGORY 129 - FUNCTION 52H - SET CALIBRATION
  2860. _____________________________________________
  2861. CONSTANTS
  2862. _________
  2863.  
  2864. Downloads the Touch Display Calibration constants
  2865.  
  2866.  
  2867. PARAMETER PACKET FORMAT
  2868.  
  2869. The parameter packet is a location in application
  2870. storage that contains the following data:
  2871.  
  2872.  
  2873.  *-----------------------------------------*
  2874.  | Field                        Length     |
  2875.  |-----------------------------------------|
  2876.  | Channel 1 gain constant      DWORD      |
  2877.  |-----------------------------------------|
  2878.  | Channel 2 gain constant      DWORD      |
  2879.  |-----------------------------------------|
  2880.  | Channel 3 gain constant      DWORD      |
  2881.  |-----------------------------------------|
  2882.  | Channel 4 gain constant      DWORD      |
  2883.  |-----------------------------------------|
  2884.  | X as a function of X  C[xx]  DWORD      |
  2885.  |-----------------------------------------|
  2886.  | X as a function of Y  C[xy]  DWORD      |
  2887.  |-----------------------------------------|
  2888.  | Y as a function of X  C[yx]  DWORD      |
  2889.  |-----------------------------------------|
  2890.  | Y as a function of Y  C[yy]  DWORD      |
  2891.  |-----------------------------------------|
  2892.  | X offset C[x0]               DWORD      |
  2893.  |-----------------------------------------|
  2894.  | Y offset C[y0]               DWORD      |
  2895.  *-----------------------------------------*
  2896.  
  2897.  
  2898.  
  2899. DATA PACKET FORMAT
  2900.  
  2901. None
  2902.  
  2903.  
  2904. Where
  2905.  
  2906.  
  2907.          All parameters are in double word floating point
  2908.          format.  This format is non-IEEE standard and is
  2909.          described in the IBM Personal System/2 8516 Touch
  2910.          Display Technical Reference.
  2911.  
  2912.  
  2913.  
  2914.  
  2915. Returns
  2916.  
  2917. None
  2918.  
  2919.  
  2920. Remarks:
  2921.  
  2922. This function intended for exclusive use by the
  2923. calibration utility.
  2924.  
  2925.  
  2926. CATEGORY 129 - FUNCTION 53H - READ DATA
  2927. _______________________________________
  2928.  
  2929. Reads a single packet of data from the Touch
  2930. Display controller.  The format of the data, XYZ
  2931. or Raw T1-4, depends on the data mode set using
  2932. function 54H.
  2933.  
  2934.  
  2935. PARAMETER PACKET FORMAT
  2936.  
  2937. The parameter packet is a location in application
  2938. storage where the caller indicates action to be
  2939. taken if no event queue data is available.  The
  2940. format of the parameter packet is as follows:
  2941.  
  2942.  
  2943.  *-----------------------------------------*
  2944.  | Field                        Length     |
  2945.  |-----------------------------------------|
  2946.  | Read Type                    WORD       |
  2947.  *-----------------------------------------*
  2948.  
  2949.  
  2950.  
  2951. DATA PACKET FORMAT
  2952.  
  2953. The data packet is a location in application
  2954. storage where the touch display device driver
  2955. returns to the caller a touch display event queue
  2956. record.  This record has two formats, depending on
  2957. the data type specified using function 54H.  The
  2958. two types of record are XYZ data or Raw data (the
  2959. default setting will depend on which mode has been
  2960. set using function 54H), see below:
  2961.  
  2962. XYZ data packet format
  2963.  
  2964.  
  2965.  *-----------------------------------------*
  2966.  | Field                        Length     |
  2967.  |-----------------------------------------|
  2968.  | Status                       WORD       |
  2969.  |-----------------------------------------|
  2970.  | Time                        DWORD       |
  2971.  |-----------------------------------------|
  2972.  | X value                      WORD       |
  2973.  |-----------------------------------------|
  2974.  | Y value                      WORD       |
  2975.  |-----------------------------------------|
  2976.  | Z value                      WORD       |
  2977.  |-----------------------------------------|
  2978.  | reserved                     WORD       |
  2979.  *-----------------------------------------*
  2980.  
  2981.  
  2982.  
  2983. Raw data packet format
  2984.  
  2985.  
  2986.  *-----------------------------------------*
  2987.  | Field                        Length     |
  2988.  |-----------------------------------------|
  2989.  | Status                       WORD       |
  2990.  |-----------------------------------------|
  2991.  | Time                        DWORD       |
  2992.  |-----------------------------------------|
  2993.  | Transducer 1                 WORD       |
  2994.  |-----------------------------------------|
  2995.  | Transducer 2                 WORD       |
  2996.  |-----------------------------------------|
  2997.  | Transducer 3                 WORD       |
  2998.  |-----------------------------------------|
  2999.  | Transducer 4                 WORD       |
  3000.  *-----------------------------------------*
  3001.  
  3002.  
  3003.  
  3004. Where
  3005.  
  3006.  
  3007.       Read type
  3008.         is used to determine the type of action taken if no
  3009.         event queue data is available.  The values may be:
  3010.  
  3011.           0 = Return NULL EventInfo if data not available
  3012.           1 = WAIT for data on empty queue.
  3013.           All other values reserved
  3014.  
  3015.  
  3016.       Status
  3017.  
  3018.         has the following bit level definitions for XYZ mode:
  3019.  
  3020.          Bit      Description
  3021.  
  3022.           0           1 = hardware offset adjust error
  3023.           1           1 = offset adjust error
  3024.           2           1 = floating point calculation error
  3025.           3           Reserved = 0
  3026.           4           1 = channel pegged error
  3027.           5           1 = offset adjust just occurred
  3028.           6           Reserved = 0
  3029.           7           Reserved = 0
  3030.           8           Reserved = 0
  3031.           9           Reserved = 0
  3032.           A           Reserved = 0
  3033.           B           Reserved = 0
  3034.           C           Touch screen status 2
  3035.           D           Touch screen status 1
  3036.           E           1 = selection detection on
  3037.           F           0 = XYZ packet
  3038.  
  3039.  
  3040.  
  3041.       Status
  3042.  
  3043.         has the following bit level definitions for RAW mode:
  3044.  
  3045.          Bit      Description
  3046.  
  3047.           1           Reserved = 0
  3048.           2           Reserved = 0
  3049.           3           Reserved = 0
  3050.           4           Reserved = 0
  3051.           5           Reserved = 0
  3052.           6           1 = channel pegged
  3053.           7           Reserved = 0
  3054.           8           Reserved = 0
  3055.           9           Reserved = 0
  3056.           A           1 = Adjust just occurred
  3057.           B           Reserved = 0
  3058.           C           Reserved = 0
  3059.           D           Reserved = 0
  3060.           E           1 = offset error
  3061.           F           1 = RAW data
  3062.           C           Touch screen status 2
  3063.           D           Touch screen status 1
  3064.           E           1 = selection detection on
  3065.           F           0 = XYZ packet
  3066.  
  3067.       Time
  3068.         is the timestamp in milliseconds
  3069.  
  3070.       X value
  3071.         is the touch contact x (horizontal) position
  3072.  
  3073.       Y value
  3074.         is the touch contact y (vertical) position
  3075.  
  3076.       Z value
  3077.         is proportional to the touch contact force
  3078.  
  3079.       Transducer n
  3080.         is the raw transducer output value.  Transducers are
  3081.         numbered clockwise from top left.
  3082.  
  3083.  
  3084.  
  3085. Returns
  3086.  
  3087. This function returns to the caller a touch event
  3088. from the touch event (FIFO) queue flags.
  3089.  
  3090.  
  3091. Remarks:
  3092.  
  3093.  
  3094. CATEGORY 129 - FUNCTION 54H - SET DATA MODE
  3095. ___________________________________________
  3096.  
  3097. Set Data Mode - causes the touch display to report
  3098. either XYZ type data or raw T1-T4 strain gauge
  3099. data
  3100.  
  3101.  
  3102. PARAMETER PACKET FORMAT
  3103.  
  3104. The parameter packet is a location in application
  3105. storage that contains the following data:
  3106.  
  3107.  
  3108.  *-----------------------------------------*
  3109.  | Field                        Length     |
  3110.  |-----------------------------------------|
  3111.  | Mode                         DWORD      |
  3112.  *-----------------------------------------*
  3113.  
  3114.  
  3115.  
  3116. DATA PACKET FORMAT
  3117.  
  3118. None
  3119.  
  3120.  
  3121. Where
  3122.  
  3123.  
  3124.        Mode
  3125.          Selects the relevant data packet reporting mode
  3126.           0 = XYZ mode
  3127.           1 = RAW mode
  3128.  
  3129.        see Function 53H for the data packet formats
  3130.  
  3131.  
  3132.  
  3133. Returns
  3134.  
  3135. None
  3136.  
  3137.  
  3138. Remarks:
  3139.  
  3140. RAW mode is intended for exclusive use by the
  3141. calibration utility.
  3142.  
  3143.  
  3144. CATEGORY 129 - FUNCTION 55H - SET CLICK LOCK
  3145. ____________________________________________
  3146. PARAMETERS
  3147. __________
  3148.  
  3149. Specifies the Touch Display Click Lock Parameters
  3150.  
  3151.  
  3152. PARAMETER PACKET FORMAT
  3153.  
  3154. The data packet is a location in application
  3155. storage that contains the following data:
  3156.  
  3157.  
  3158.  *-----------------------------------------*
  3159.  | Field                        Length     |
  3160.  |-----------------------------------------|
  3161.  | Active Area                  WORD       |
  3162.  |-----------------------------------------|
  3163.  | Timeout Period               WORD       |
  3164.  |-----------------------------------------|
  3165.  | Click Count                  BYTE       |
  3166.  *-----------------------------------------*
  3167.  
  3168.  
  3169.  
  3170. DATA PACKET FORMAT
  3171.  
  3172. None
  3173.  
  3174.  
  3175. Where
  3176.  
  3177.  
  3178.       Active Area
  3179.          Specifies the X/Y pixel area that will cause a mouse emulation
  3180.          button 1 click (push harder threshold) to be held within a defined
  3181.          X/Y coordinate of first selection.
  3182.  
  3183.       Timeout Period
  3184.          Specifies the length of time in milliseconds that will cause a
  3185.          mouse emulation button 1 click to be held for, within a defined
  3186.          active area.
  3187.  
  3188.       Click Count
  3189.          Specifies the mouse emulation button 1 clicks that will be held
  3190.          within a defined area for a defined period of time.
  3191.  
  3192.          Value:
  3193.          0 = click locking off (default)
  3194.          1 = single button click locking
  3195.          2 = double button click locking
  3196.  
  3197.   Note:
  3198.   Any parameter value of '-1' will cause the driver default value to be
  3199.   substituted.
  3200.  
  3201.  
  3202.  
  3203. Returns
  3204.  
  3205. None
  3206.  
  3207.  
  3208. Remarks:
  3209.  
  3210. This function is particularly useful for
  3211. manipulation of small areas using mouse emulation,
  3212. for example moving Presentation Manager icons,
  3213. etc.  It is used by the Touch Control Panel
  3214. utility.
  3215.  
  3216.  
  3217. CATEGORY 129 - FUNCTION 56H - SET TOUCH THRESHOLDS
  3218. __________________________________________________
  3219.  
  3220. Specifies the Touch Display Thresholds
  3221.  
  3222.  
  3223. PARAMETER PACKET FORMAT
  3224.  
  3225. The parameter packet is a location in application
  3226. storage that contains the following data:
  3227.  
  3228.  
  3229.  *-----------------------------------------*
  3230.  | Field                        Length     |
  3231.  |-----------------------------------------|
  3232.  | On Screen threshold          WORD       |
  3233.  |-----------------------------------------|
  3234.  | Push threshold               WORD       |
  3235.  |-----------------------------------------|
  3236.  | Push hysteresis threshold    WORD       |
  3237.  *-----------------------------------------*
  3238.  
  3239.  
  3240.  
  3241. DATA PACKET FORMAT
  3242.  
  3243. None
  3244.  
  3245.  
  3246. Where
  3247.  
  3248.  
  3249.       On Screen threshold
  3250.          sets the value of Z on the chosen Z scale at which the touch
  3251.          display will interpret the touch contact force as 'On screen' and
  3252.          start reporting data.  Data will only be reported while the force
  3253.          exceeds this threshold.
  3254.  
  3255.       Push threshold
  3256.          sets the value of Z, when Z is increasing, on the chosen Z scale
  3257.          at which the touch display will set the selection detection bit
  3258.          in the status returned by function 53H.
  3259.  
  3260.       Push hysteresis threshold
  3261.          sets the value of Z, when Z is decreasing, on the chosen Z scale
  3262.          at which the touch display will reset the selection detection bit
  3263.          in the status returned by function 53H.
  3264.  
  3265.   Note:
  3266.   Any parameter value of '-1' will cause the driver default value to be
  3267.   substituted.
  3268.  
  3269.  
  3270.  
  3271. Returns
  3272.  
  3273. None
  3274.  
  3275.  
  3276. Remarks:
  3277.  
  3278. Push and push hysteresis thresholds are only
  3279. relevant when the selection detection mechanism of
  3280. 'Push harder' is set (see function 52H of the
  3281. device independent IOCTl's.
  3282.  
  3283.  
  3284. CATEGORY 129 - FUNCTION 57H - SET EMULATION XY
  3285. ______________________________________________
  3286. OFFSET
  3287. ______
  3288.  
  3289. Specifies the Touch Display XY Offset applied to
  3290. touch data when passed as emulated mouse data.
  3291.  
  3292.  
  3293. PARAMETER PACKET FORMAT
  3294.  
  3295. The parameter packet is a location in application
  3296. storage that contains the following data:
  3297.  
  3298.  
  3299.  *-----------------------------------------*
  3300.  | Field                        Length     |
  3301.  |-----------------------------------------|
  3302.  | X offset                     WORD       |
  3303.  |-----------------------------------------|
  3304.  | Y offset                     WORD       |
  3305.  *-----------------------------------------*
  3306.  
  3307.  
  3308.  
  3309. DATA PACKET FORMAT
  3310.  
  3311. None
  3312.  
  3313.  
  3314. Where
  3315.  
  3316.  
  3317.       X offset
  3318.          indicates the amount by which the X coordinate will be
  3319.          offset.
  3320.  
  3321.       Y offset
  3322.          indicates the amount by which the Y coordinate will be
  3323.          offset.
  3324.  
  3325.  
  3326.  
  3327. Returns
  3328.  
  3329. None
  3330.  
  3331.  
  3332. Remarks:
  3333.  
  3334. Calls to the mouse device independent driver via
  3335. the IDC will have the x and y coordinate offsets
  3336. applied to the touch x,y,z data.  Data supplied to
  3337. the touch device independent driver is not
  3338. affected.
  3339.  
  3340.  
  3341. CATEGORY 129 - FUNCTION 58H - SET DATA REPORT RATE
  3342. __________________________________________________
  3343.  
  3344. Specifies the Touch Display Data Report Rate
  3345.  
  3346.  
  3347. PARAMETER PACKET FORMAT
  3348.  
  3349. The parameter packet is a location in application
  3350. storage that contains the following data:
  3351.  
  3352.  
  3353.  *-----------------------------------------*
  3354.  | Field                        Length     |
  3355.  |-----------------------------------------|
  3356.  | Report rate                  WORD       |
  3357.  *-----------------------------------------*
  3358.  
  3359.  
  3360.  
  3361. DATA PACKET FORMAT
  3362.  
  3363. None
  3364.  
  3365.  
  3366. Where
  3367.  
  3368.  
  3369.       Report rate
  3370.          sets the maximum rate at which data packets will be
  3371.          returned by the touch display while the touch contact force
  3372.          exceeds the On Screen threshold (see function 56H).
  3373.  
  3374.          Value:
  3375.          0 = 10 reports per second
  3376.          1 = 20 reports per second
  3377.          2 = 30 reports per second
  3378.          3 = 40 reports per second
  3379.          4 = 60 reports per second
  3380.          -1 = driver default value
  3381.          All other values reserved.
  3382.  
  3383.  
  3384.  
  3385. Returns
  3386.  
  3387. None
  3388.  
  3389.  
  3390. Remarks:
  3391.  
  3392.  
  3393. CATEGORY 129 - FUNCTION 59H - SET LOW PASS FILTER
  3394. _________________________________________________
  3395.  
  3396. Specifies the Touch Display Low Pass Filter
  3397. Parameters
  3398.  
  3399.  
  3400. PARAMETER PACKET FORMAT
  3401.  
  3402. The parameter packet is a location in application
  3403. storage that contains the following data:
  3404.  
  3405.  
  3406.  *-----------------------------------------*
  3407.  | Field                        Length     |
  3408.  |-----------------------------------------|
  3409.  | Filter type                  USHORT     |
  3410.  |-----------------------------------------|
  3411.  | Filter frequency             USHORT     |
  3412.  *-----------------------------------------*
  3413.  
  3414.  
  3415.  
  3416. DATA PACKET FORMAT
  3417.  
  3418. None
  3419.  
  3420.  
  3421. Where
  3422.  
  3423.  
  3424.       Filter type
  3425.         Determines the type of low pass filter to be used
  3426.  
  3427.         Value:
  3428.         0 = Default (Touch Display)
  3429.         1 = Alternative (Touch Panel)
  3430.         All other values reserved
  3431.  
  3432.  
  3433.       Filter frequency
  3434.         Determines the frequency cut off value for the filter
  3435.  
  3436.         Value:
  3437.         0 = Default (Medium)
  3438.         1 = Slow
  3439.         2 = Medium
  3440.         3 = Fast
  3441.         4 = Rapid
  3442.         All other values reserved
  3443.  
  3444.  
  3445.  
  3446.  
  3447. Returns
  3448.  
  3449. None.
  3450.  
  3451.  
  3452. Remarks:
  3453.  
  3454. This function is used by the Touch Control Panel.
  3455.  
  3456.  
  3457. CATEGORY 129 - FUNCTION 5AH - WRITE MEMORY
  3458. __________________________________________
  3459. LOCATION
  3460. ________
  3461.  
  3462. Write a byte to Touch Display controller RAM
  3463.  
  3464.  
  3465. PARAMETER PACKET FORMAT
  3466.  
  3467. The parameter packet is a location in application
  3468. storage that contains the following data:
  3469.  
  3470.  
  3471.  *-----------------------------------------*
  3472.  | Field                        Length     |
  3473.  |-----------------------------------------|
  3474.  | Data to write                BYTE       |
  3475.  |-----------------------------------------|
  3476.  | Address to write at          WORD       |
  3477.  *-----------------------------------------*
  3478.  
  3479.  
  3480.  
  3481. DATA PACKET FORMAT
  3482.  
  3483. None
  3484.  
  3485.  
  3486. Returns
  3487.  
  3488. None
  3489.  
  3490.  
  3491. Remarks:
  3492.  
  3493.  
  3494. CATEGORY 129 - FUNCTION 5B - 5FH - RESERVED
  3495. ___________________________________________
  3496.  
  3497.  
  3498. CATEGORY 129 - FUNCTION 60H - GET CALIBRATION
  3499. _____________________________________________
  3500. CONSTANTS
  3501. _________
  3502.  
  3503. Gets the Touch Display Calibration constants
  3504.  
  3505.  
  3506. PARAMETER PACKET FORMAT
  3507.  
  3508. None
  3509.  
  3510.  
  3511. DATA PACKET FORMAT
  3512.  
  3513. The data packet is a location in application
  3514. storage where the Touch Display Device driver will
  3515. return the current set of calibration constants.
  3516. The format is as follows:
  3517.  
  3518.  
  3519.  *-----------------------------------------*
  3520.  | Field                        Length     |
  3521.  |-----------------------------------------|
  3522.  | Channel 1 gain constant      DWORD      |
  3523.  |-----------------------------------------|
  3524.  | Channel 2 gain constant      DWORD      |
  3525.  |-----------------------------------------|
  3526.  | Channel 3 gain constant      DWORD      |
  3527.  |-----------------------------------------|
  3528.  | Channel 4 gain constant      DWORD      |
  3529.  |-----------------------------------------|
  3530.  | X as a function of X  C[xx]  DWORD      |
  3531.  |-----------------------------------------|
  3532.  | X as a function of Y  C[xy]  DWORD      |
  3533.  |-----------------------------------------|
  3534.  | Y as a function of X  C[yx]  DWORD      |
  3535.  |-----------------------------------------|
  3536.  | Y as a function of Y  C[yy]  DWORD      |
  3537.  |-----------------------------------------|
  3538.  | X offset C[x0]               DWORD      |
  3539.  |-----------------------------------------|
  3540.  | Y offset C[y0]               DWORD      |
  3541.  *-----------------------------------------*
  3542.  
  3543.  
  3544.  
  3545. Where
  3546.  
  3547.  
  3548.          All parameters are in double word floating point
  3549.          format.  This format is non-IEEE standard and is
  3550.          described in the IBM Personal System/2 8516 Touch
  3551.          Display Technical Reference.
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557. Returns
  3558.  
  3559. None
  3560.  
  3561.  
  3562. Remarks:
  3563.  
  3564. This function intended for exclusive use by the
  3565. calibration utility
  3566.  
  3567.  
  3568. CATEGORY 129 - FUNCTION 61H - GET DATA MODE
  3569. ___________________________________________
  3570.  
  3571. Gets the Current Touch Display data packet
  3572. reporting mode
  3573.  
  3574.  
  3575. PARAMETER PACKET FORMAT
  3576.  
  3577. None
  3578.  
  3579.  
  3580. DATA PACKET FORMAT
  3581.  
  3582. The data packet is a location in application
  3583. storage where the touch display driver will return
  3584. to the caller the current data packet reporting
  3585. mode The format is as follows:
  3586.  
  3587.  
  3588.  *-----------------------------------------*
  3589.  | Field                        Length     |
  3590.  |-----------------------------------------|
  3591.  | Mode                         WORD       |
  3592.  *-----------------------------------------*
  3593.  
  3594.  
  3595.  
  3596. Where
  3597.  
  3598.  
  3599.        Mode
  3600.          Indicates the current data packet reporting mode
  3601.           0 = XYZ mode
  3602.           1 = RAW mode
  3603.  
  3604.        see Function 53H for the data packet formats
  3605.  
  3606.  
  3607.  
  3608.  
  3609. Returns
  3610.  
  3611. This function returns to the caller Current Touch
  3612. Display data packet reporting mode.
  3613.  
  3614.  
  3615. CATEGORY 129 - FUNCTION 62H - GET CLICK LOCK
  3616. ____________________________________________
  3617. PARAMETERS
  3618. __________
  3619.  
  3620. Gets the Touch Display Click Lock Parameters
  3621.  
  3622.  
  3623. PARAMETER PACKET FORMAT
  3624.  
  3625. None
  3626.  
  3627.  
  3628. DATA PACKET FORMAT
  3629.  
  3630. The data packet is a location in application
  3631. storage where the touch display device driver
  3632. returns to the caller the current click locking
  3633. settings.  The format is as follows:
  3634.  
  3635.  
  3636.  *-----------------------------------------*
  3637.  | Field                        Length     |
  3638.  |-----------------------------------------|
  3639.  | Active Area                  WORD       |
  3640.  |-----------------------------------------|
  3641.  | Timeout Period               WORD       |
  3642.  |-----------------------------------------|
  3643.  | Click Count                  WORD       |
  3644.  *-----------------------------------------*
  3645.  
  3646.  
  3647.  
  3648. Where
  3649.  
  3650.  
  3651.       Active Area
  3652.          Specifies the X/Y pixel area that will cause a mouse emulation
  3653.          button 1 click (push harder threshold) to be held within a defined
  3654.          X/Y coordinate of first selection.
  3655.  
  3656.       Timeout Period
  3657.          Specifies the length of time in milliseconds that will cause a
  3658.          mouse emulation button 1 click to be held for, within a defined
  3659.          active area.
  3660.  
  3661.       Click Count
  3662.          Specifies the mouse emulation button 1 clicks that will be held
  3663.          within a defined area for a defined period of time.
  3664.  
  3665.          Value:
  3666.          0 = click locking off (default)
  3667.          1 = single button click locking
  3668.          2 = double button click locking
  3669.  
  3670.  
  3671.  
  3672. Returns
  3673.  
  3674. This function returns to the caller the mouse
  3675. emulation click locking settings.
  3676.  
  3677.  
  3678. Remarks:
  3679.  
  3680. This function is particularly useful for
  3681. manipulation of small areas using mouse emulation,
  3682. for example moving Presentation Manager icons,
  3683. etc.
  3684.  
  3685. The tendency of the emulated mouse position to
  3686. change while attempting to button click can be
  3687. eliminated with only a small initial 'hesitation'
  3688. noted as a side affect while attempting to drag
  3689. the cursor.
  3690.  
  3691. A setting of 3-500 ms for the timeout period is
  3692. recommended, while the active area setting will
  3693. depend on the screen pixel resolution: as a guide
  3694. use a value approximately equal to half the size
  3695. of an icon.
  3696.  
  3697.  
  3698. CATEGORY 129 - FUNCTION 63H - GET TOUCH THRESHOLDS
  3699. __________________________________________________
  3700.  
  3701. Gets the Current Touch Display Thresholds
  3702.  
  3703.  
  3704. PARAMETER PACKET FORMAT
  3705.  
  3706. None
  3707.  
  3708.  
  3709. DATA PACKET FORMAT
  3710.  
  3711. The data packet is a location in application
  3712. storage where the touch display driver will return
  3713. to the caller the current touch display threshold
  3714. settings.  The format is as follows:
  3715.  
  3716.  
  3717.  *-----------------------------------------*
  3718.  | Field                        Length     |
  3719.  |-----------------------------------------|
  3720.  | On Screen threshold          WORD       |
  3721.  |-----------------------------------------|
  3722.  | Push threshold               WORD       |
  3723.  |-----------------------------------------|
  3724.  | Push hysteresis threshold    WORD       |
  3725.  *-----------------------------------------*
  3726.  
  3727.  
  3728.  
  3729. Where
  3730.  
  3731.  
  3732.       On Screen threshold
  3733.          is the value of Z on the chosen Z scale at which the touch
  3734.          display will interpret the touch contact force as 'On screen' and
  3735.          start reporting data.  Data will only be reported while the force
  3736.          exceeds this threshold.
  3737.  
  3738.       Push threshold
  3739.          is the value of Z, when Z is increasing, on the chosen Z scale at
  3740.          which the touch display will set the selection detection bit in
  3741.          the status returned by function 53H.
  3742.  
  3743.       Push hysteresis threshold
  3744.          is the value of Z, when Z is decreasing, on the chosen Z scale at
  3745.          which the touch display will reset the selection detection bit in
  3746.          the status returned by function 53H.
  3747.  
  3748.  
  3749.  
  3750. Returns
  3751.  
  3752. This function returns to the caller the current
  3753. threshold values.
  3754.  
  3755.  
  3756. Remarks:
  3757.  
  3758. Push and push hysteresis thresholds are only
  3759. relevant when the selection detection mechanism of
  3760. 'Push harder' is set (see device independent
  3761. IOCTls function 52H).
  3762.  
  3763.  
  3764. CATEGORY 129 - FUNCTION 64H - GET EMULATION XY
  3765. ______________________________________________
  3766. OFFSET
  3767. ______
  3768.  
  3769. Gets the Touch Display XY Offsets applied during
  3770. mouse emulation.
  3771.  
  3772.  
  3773. PARAMETER PACKET FORMAT
  3774.  
  3775. None
  3776.  
  3777.  
  3778. DATA PACKET FORMAT
  3779.  
  3780. The data packet is a location in application
  3781. storage where the touch display driver will return
  3782. to the caller the values of the x and y offsets
  3783. which are added to the basic x,y data before being
  3784. supplied to the mouse device independent driver
  3785. via its absolute IDC entry point.  The format is
  3786. as follows:
  3787.  
  3788.  
  3789.  *-----------------------------------------*
  3790.  | Field                        Length     |
  3791.  |-----------------------------------------|
  3792.  | X offset                     WORD       |
  3793.  |-----------------------------------------|
  3794.  | Y offset                     WORD       |
  3795.  *-----------------------------------------*
  3796.  
  3797.  
  3798.  
  3799. Where
  3800.  
  3801.  
  3802.       X offset
  3803.         indicates the amount by which the X coordinate will be offset.
  3804.  
  3805.       Y offset
  3806.         indicates the amount by which the Y coordinate will be offset.
  3807.  
  3808.  
  3809.  
  3810.  
  3811. Returns
  3812.  
  3813. This function returns to the caller the current X
  3814. and Y coordinate offsets applied during mouse
  3815. emulation.
  3816.  
  3817.  
  3818. Remarks:
  3819.  
  3820. This function is used by the Touch Control Panel
  3821. and is used in order to offset the mouse pointer
  3822. image from the finger, to enable the image to be
  3823. seen while touching the screen.
  3824.  
  3825.  
  3826. CATEGORY 129 - FUNCTION 65H - GET DATA REPORT RATE
  3827. __________________________________________________
  3828.  
  3829. Gets the Current Touch Display data packet report
  3830. rate.
  3831.  
  3832.  
  3833. PARAMETER PACKET FORMAT
  3834.  
  3835. None
  3836.  
  3837.  
  3838. DATA PACKET FORMAT
  3839.  
  3840. The data packet is a location in application
  3841. storage where the touch display driver will return
  3842. to the caller the touch display maximum data
  3843. reporting rate.  The format is as follows:
  3844.  
  3845.  
  3846.  *-----------------------------------------*
  3847.  | Field                        Length     |
  3848.  |-----------------------------------------|
  3849.  | Report rate                  WORD       |
  3850.  *-----------------------------------------*
  3851.  
  3852.  
  3853.  
  3854. Where
  3855.  
  3856.  
  3857.       Report rate
  3858.          is the maximum rate at which data packets will be returned
  3859.          by the touch display while the touch contact force exceeds
  3860.          the On Screen threshold (see function 56H).
  3861.  
  3862.          Value:
  3863.          0 = 10 reports per second
  3864.          1 = 20 reports per second
  3865.          2 = 30 reports per second
  3866.          3 = 40 reports per second
  3867.          4 = 60 reports per second
  3868.          All other values reserved.
  3869.  
  3870.  
  3871.  
  3872.  
  3873. Returns
  3874.  
  3875. This function returns to the caller the data
  3876. report rate.
  3877.  
  3878.  
  3879. Remarks:
  3880.  
  3881. The actual reporting rate may vary up to the
  3882. maximum quoted rate.
  3883.  
  3884.  
  3885. CATEGORY 129 - FUNCTION 66H - GET LOW PASS FILTER
  3886. _________________________________________________
  3887.  
  3888. Gets the Current Touch Display Low Pass Filter
  3889. Parameters
  3890.  
  3891.  
  3892. PARAMETER PACKET FORMAT
  3893.  
  3894. None
  3895.  
  3896.  
  3897. DATA PACKET FORMAT
  3898.  
  3899. The data packet is a location in application
  3900. storage where the touch display driver will return
  3901. to the caller the low pass filter settings.  The
  3902. format is as follows:
  3903.  
  3904.  
  3905.  *-----------------------------------------*
  3906.  | Field                        Length     |
  3907.  |-----------------------------------------|
  3908.  | Filter type                  USHORT     |
  3909.  |-----------------------------------------|
  3910.  | Filter frequency             USHORT     |
  3911.  *-----------------------------------------*
  3912.  
  3913.  
  3914.  
  3915. Where
  3916.  
  3917.  
  3918.       Filter type
  3919.         Indicates the type of low pass filter being used
  3920.  
  3921.         Value:
  3922.         0 = Default (Touch Display)
  3923.         1 = Alternative (Touch Panel)
  3924.         All other values reserved
  3925.  
  3926.  
  3927.       Filter frequency
  3928.         Indicates the frequency cut off value for the filter
  3929.  
  3930.         Value:
  3931.         0 = Default (Medium)
  3932.         1 = Slow
  3933.         2 = Medium
  3934.         3 = Fast
  3935.         4 = Rapid
  3936.         All other values reserved
  3937.  
  3938.  
  3939.  
  3940. Returns
  3941.  
  3942. This function returns to the caller the low pass
  3943. filter settings.
  3944.  
  3945.  
  3946. Remarks:
  3947.  
  3948. A single set of filter constants set in one screen
  3949. group apply screen group wide.  The Touch Control
  3950. Panel makes use of this function.
  3951.  
  3952.  
  3953. CATEGORY 129 - FUNCTION 67H - READ MEMORY LOCATION
  3954. __________________________________________________
  3955.  
  3956. Reads a byte from Touch Display controller RAM
  3957.  
  3958.  
  3959. PARAMETER PACKET FORMAT
  3960.  
  3961. None
  3962.  
  3963.  
  3964. DATA PACKET FORMAT
  3965.  
  3966. The parameter packet is a location in application
  3967. storage that contains the following data:
  3968.  
  3969.  
  3970.  *-----------------------------------------*
  3971.  | Field                        Length     |
  3972.  |-----------------------------------------|
  3973.  | Data read from RAM           BYTE       |
  3974.  |-----------------------------------------|
  3975.  | Address to read from         WORD       |
  3976.  *-----------------------------------------*
  3977.  
  3978.  
  3979.  
  3980. Returns
  3981.  
  3982. None
  3983.  
  3984.  
  3985. Remarks:
  3986.  
  3987.  
  3988. SUMMARY: DEVICE INDEPENDENT DRIVER
  3989. __________________________________
  3990.  
  3991. +------------------------------------------------+
  3992. | Table 2.  Category 129 TOUCH$ Device IOCtl     |
  3993. |          Commands                              |
  3994. +-------+----------------------------------------+
  3995. | 50h   | Set Coordinate System                  |
  3996. +-------+----------------------------------------+
  3997. | 51h   | Reserved                               |
  3998. +-------+----------------------------------------+
  3999. | 52h   | Set Selection Mechanism                |
  4000. +-------+----------------------------------------+
  4001. | 53h   | Set Event Mask                         |
  4002. +-------+----------------------------------------+
  4003. | 54h   | Set Queue Size                         |
  4004. +-------+----------------------------------------+
  4005. | 55h   | Set Emulation State                    |
  4006. +-------+----------------------------------------+
  4007. | 60h   | Get Coordinate System                  |
  4008. +-------+----------------------------------------+
  4009. | 61h   | Get Coordinate Origin                  |
  4010. +-------+----------------------------------------+
  4011. | 62h   | Get Selection Mechanism                |
  4012. +-------+----------------------------------------+
  4013. | 63h   | Get Event Mask                         |
  4014. +-------+----------------------------------------+
  4015. | 64h   | Get Queue Size                         |
  4016. +-------+----------------------------------------+
  4017. | 65h   | Get Emulation State                    |
  4018. +-------+----------------------------------------+
  4019. | 66h   | Read Event Queue                       |
  4020. +-------+----------------------------------------+
  4021.  
  4022.  
  4023. CATEGORY 129 - FUNCTION 50H
  4024. ___________________________
  4025.  
  4026. Specifies the Touch Display coordinate system
  4027.  
  4028.  
  4029. PARAMETER PACKET FORMAT
  4030.  
  4031. The parameter packet is a location in application
  4032. storage that contains the following data:
  4033.  
  4034.  
  4035.  *-----------------------------------------*
  4036.  | Field                        Length     |
  4037.  |-----------------------------------------|
  4038.  | X min                        WORD       |
  4039.  |-----------------------------------------|
  4040.  | X max                        WORD       |
  4041.  |-----------------------------------------|
  4042.  | Y min                        WORD       |
  4043.  |-----------------------------------------|
  4044.  | Y max                        WORD       |
  4045.  |-----------------------------------------|
  4046.  | Z min                        WORD       |
  4047.  |-----------------------------------------|
  4048.  | Z max                        WORD       |
  4049.  |-----------------------------------------|
  4050.  | X hysteresis                 WORD       |
  4051.  |-----------------------------------------|
  4052.  | X hysteresis                 WORD       |
  4053.  *-----------------------------------------*
  4054.  
  4055.  
  4056.  
  4057. DATA PACKET FORMAT
  4058.  
  4059. None
  4060.  
  4061.  
  4062. Where
  4063.  
  4064.  
  4065.       X min
  4066.          is the value of x to be reported at the left hand edge of
  4067.          the display.
  4068.  
  4069.       X max
  4070.          is the value of x to be reported at the right hand edge of
  4071.          the display.
  4072.  
  4073.       Y min
  4074.          is the value of y to be reported at the top edge of the
  4075.          display.
  4076.  
  4077.       Y max
  4078.          is the value of y to be reported at the bottom edge of the
  4079.          display.
  4080.  
  4081.       Z min
  4082.          is the notional value that would be reported with minimum
  4083.          contact force applied.  This is because Z values are only
  4084.          reported when they exceed the On Screen threshold.
  4085.          Values from Z min to On Screen threshold will never be reported.
  4086.  
  4087.       Z max
  4088.          is the value to be reported with maximum contact force applied
  4089.  
  4090.       X hysteresis
  4091.          is the amount of hysteresis in the horizontal direction in
  4092.          cell units multiplied by 1000.  Eg hysteresis of 0.4 will
  4093.          return 400.
  4094.  
  4095.       Y hysteresis
  4096.          is the amount of hysteresis in the horizontal direction in
  4097.          cell units multiplied by 1000.  Eg hysteresis of 0.4 will
  4098.          return 400.
  4099.  
  4100.  
  4101.  
  4102. Returns
  4103.  
  4104. None
  4105.  
  4106.  
  4107. Remarks:
  4108.  
  4109. X, and Y values are treated as 16 bit 2's
  4110. complement signed integers in the range -32768 to
  4111. 32767.
  4112.  
  4113. Hysteresis values are unsigned integers in the
  4114. range 0 - 65535.
  4115.  
  4116. Hysteresis values required should be expressed in
  4117. terms of the hysteresis value, in X,Y coordinate
  4118. system units, multiplied by 1000.
  4119.  
  4120.  
  4121. CATEGORY 129 - FUNCTION 51H
  4122. ___________________________
  4123.  
  4124. Performs no function: reserved
  4125.  
  4126.  
  4127. CATEGORY 129 - FUNCTION 52H
  4128. ___________________________
  4129.  
  4130. Specifies the Touch Display Selection Mechanism
  4131. method
  4132.  
  4133.  
  4134. PARAMETER PACKET FORMAT
  4135.  
  4136. The parameter packet is a location in application
  4137. storage that contains the following data:
  4138.  
  4139.  
  4140.  *-----------------------------------------*
  4141.  | Field                        Length     |
  4142.  |-----------------------------------------|
  4143.  | Type                         WORD       |
  4144.  |-----------------------------------------|
  4145.  | Number of stable points      WORD       |
  4146.  |-----------------------------------------|
  4147.  | Tolerance value              WORD       |
  4148.  |-----------------------------------------|
  4149.  | Stable region length         WORD       |
  4150.  *-----------------------------------------*
  4151.  
  4152.  
  4153.  
  4154. DATA PACKET FORMAT
  4155.  
  4156. None
  4157.  
  4158.  
  4159. Where
  4160.  
  4161.  
  4162.       Type
  4163.          the in which the selection detection flag (bit)
  4164.          in the status word returned in function 66H is set/reset
  4165.  
  4166.          Bit 0
  4167.            0 = Push harder (default)
  4168.            1 = Lift off
  4169.          Bit 1
  4170.            0 = First value taken
  4171.            1 = Single touch algorithm applied
  4172.          Bit 2
  4173.            0 = First value taken
  4174.            1 = Stable region algorithm active
  4175.          Bit 3-F
  4176.            0 = Reserved
  4177.  
  4178.  
  4179.       Number of stable points
  4180.  
  4181.          Value:
  4182.             0 = default
  4183.             n = # of stable points
  4184.  
  4185.       Tolerance value
  4186.             0 = default
  4187.             n = tolerance in pixels
  4188.  
  4189.       Stable region length
  4190.             0 = default
  4191.             n = region length in samples ( 0 < n < 60 )
  4192.  
  4193.  
  4194.  
  4195.  
  4196. Returns
  4197.  
  4198. None
  4199.  
  4200.  
  4201. Remarks:
  4202.  
  4203. For information on the single touch and stable
  4204. region algorithms, see under -- Heading 'BISTAL'
  4205. unknown --.
  4206.  
  4207.  
  4208. CATEGORY 129 - FUNCTION 53H
  4209. ___________________________
  4210.  
  4211. Assigns a new Touch Display Event Mask
  4212.  
  4213.  
  4214. PARAMETER PACKET FORMAT
  4215.  
  4216. The parameter packet is a location in application
  4217. storage that contains the following data:
  4218.  
  4219.  
  4220.  *-----------------------------------------*
  4221.  | Field                        Length     |
  4222.  |-----------------------------------------|
  4223.  | Event Mask                   WORD       |
  4224.  *-----------------------------------------*
  4225.  
  4226.  
  4227.  
  4228. DATA PACKET FORMAT
  4229.  
  4230. None
  4231.  
  4232.  
  4233. Where
  4234.  
  4235.  
  4236.       Event mask
  4237.  
  4238.       Bit      Meaning
  4239.  
  4240.        0         1 = On Screen status set event
  4241.        1         1 = Touch Down event (On Screen status clear to set)
  4242.        2         1 = Lift Off event (On Screen status set to clear)
  4243.        3         1 = Selection Detection flag set event
  4244.        4         1 = Selection Detection flag clear to set event
  4245.        5         1 = Selection Detection flag set to clear event
  4246.        6-F       Reserved = 0
  4247.  
  4248.  
  4249.  
  4250. Returns
  4251.  
  4252. None
  4253.  
  4254.  
  4255. Remarks:
  4256.  
  4257. The touch display device driver gets the new mask
  4258. for enabled/disabled touch display device events
  4259. from the caller's parameter packet.  The mask
  4260. determines which events are to be queued, that is
  4261. readable by calling Category 129, Function 66H.
  4262.  
  4263.  
  4264. CATEGORY 129 - FUNCTION 54H
  4265. ___________________________
  4266.  
  4267. Sets the Touch Display event queue size.
  4268.  
  4269.  
  4270. PARAMETER PACKET FORMAT
  4271.  
  4272. The parameter packet is a location in application
  4273. storage that contains the following data:
  4274.  
  4275.  
  4276.  *-----------------------------------------*
  4277.  | Field                        Length     |
  4278.  |-----------------------------------------|
  4279.  | Queue Size                   WORD       |
  4280.  *-----------------------------------------*
  4281.  
  4282.  
  4283.  
  4284. DATA PACKET FORMAT
  4285.  
  4286. None
  4287.  
  4288.  
  4289. Where
  4290.  
  4291.  
  4292.       Queue Size
  4293.         indicates how many touch display events into the past
  4294.         will be stored in the event queue.
  4295.  
  4296.  
  4297.  
  4298. Returns
  4299.  
  4300. None
  4301.  
  4302.  
  4303. Remarks:
  4304.  
  4305. The queue size set may be any value from 1 to a
  4306. maximum of the QSIZE parameter specified in the
  4307. device driver CONFIG.SYS statement (which defaults
  4308. to 10 if not specified).
  4309.  
  4310.  
  4311. CATEGORY 129 - FUNCTION 55H
  4312. ___________________________
  4313.  
  4314. Specifies the Touch Display mouse emulation state:
  4315. on or off.
  4316.  
  4317.  
  4318. PARAMETER PACKET FORMAT
  4319.  
  4320. The parameter packet is a location in application
  4321. storage that contains the following data:
  4322.  
  4323.  
  4324.  *-----------------------------------------*
  4325.  | Field                        Length     |
  4326.  |-----------------------------------------|
  4327.  | Emul state                   WORD       |
  4328.  *-----------------------------------------*
  4329.  
  4330.  
  4331.  
  4332. DATA PACKET FORMAT
  4333.  
  4334. None
  4335.  
  4336.  
  4337. Where
  4338.  
  4339.  
  4340.       Emul state
  4341.         switch which turns mouse emulation on or off for the screen
  4342.         group.
  4343.  
  4344.          Bit      Description
  4345.  
  4346.           0       Screen group emulation
  4347.                   =0 = Emulation off, =1 = Emulation on
  4348.           1-F     Reserved
  4349.  
  4350.  
  4351.  
  4352. Returns
  4353.  
  4354. None
  4355.  
  4356.  
  4357. Remarks:
  4358.  
  4359. Calls the device dependent driver via the IDC to
  4360. set/reset the emulation state.
  4361.  
  4362. Using this function, emulation can be turned on
  4363. after the touch device is opened (the act of which
  4364. disables emulation temporarily), assuming that
  4365. emulation is available with EMUL= 1 specified in
  4366. the touch display TOUCH.INI configuration file.
  4367.  
  4368.  
  4369. CATEGORY 129 - FUNCTION 60H
  4370. ___________________________
  4371.  
  4372. Gets the Touch Display coordinate system
  4373.  
  4374.  
  4375. PARAMETER PACKET FORMAT
  4376.  
  4377. None
  4378.  
  4379.  
  4380. DATA PACKET FORMAT
  4381.  
  4382. The data packet is a location in application
  4383. storage where the touch display driver will return
  4384. to the caller the coordinate system being used to
  4385. report X,Y,Z data report values, including maximum
  4386. and minimum limits and change report hysteresis
  4387. values.  The format is as follows:
  4388.  
  4389.  
  4390.  *-----------------------------------------*
  4391.  | Field                        Length     |
  4392.  |-----------------------------------------|
  4393.  | X min                        WORD       |
  4394.  |-----------------------------------------|
  4395.  | X max                        WORD       |
  4396.  |-----------------------------------------|
  4397.  | Y min                        WORD       |
  4398.  |-----------------------------------------|
  4399.  | Y max                        WORD       |
  4400.  |-----------------------------------------|
  4401.  | Z min                        WORD       |
  4402.  |-----------------------------------------|
  4403.  | Z max                        WORD       |
  4404.  |-----------------------------------------|
  4405.  | X hysteresis                 WORD       |
  4406.  |-----------------------------------------|
  4407.  | X hysteresis                 WORD       |
  4408.  *-----------------------------------------*
  4409.  
  4410.  
  4411.  
  4412. Where
  4413.  
  4414.  
  4415.       X min
  4416.          is the value of x to be reported at the left hand edge of
  4417.          the display.
  4418.  
  4419.       X max
  4420.          is the value of x to be reported at the right hand edge of
  4421.          the display.
  4422.  
  4423.       Y min
  4424.          is the value of y to be reported at the top edge of the
  4425.          display.
  4426.  
  4427.       Y max
  4428.          is the value of y to be reported at the bottom edge of the
  4429.          display.
  4430.  
  4431.       Z min
  4432.          is the notional value that would be reported with minimum
  4433.          contact force applied.  This is because Z values are only
  4434.          reported when they exceed the On Screen threshold.
  4435.          Values from Z min to On Screen threshold will never be reported.
  4436.  
  4437.       Z max
  4438.          is the value to be reported with maximum contact force applied
  4439.  
  4440.       X hysteresis
  4441.          is the amount of hysteresis in the horizontal direction in
  4442.          cell units multiplied by 1000.  Eg hysteresis of 0.4 will
  4443.          return 400.
  4444.  
  4445.       Y hysteresis
  4446.          is the amount of hysteresis in the horizontal direction in
  4447.          cell units multiplied by 1000.  Eg hysteresis of 0.4 will
  4448.          return 400.
  4449.  
  4450.  
  4451.  
  4452.  
  4453. Returns
  4454.  
  4455. This function returns to the caller the current
  4456. X,Y,Z coordinate reporting range and the X,Y
  4457. coordinate change hysteresis values.
  4458.  
  4459.  
  4460. Remarks:
  4461.  
  4462. X, and Y values are 16 bit 2's complement signed
  4463. integers in the range -32768 to 32767.
  4464.  
  4465. Hysteresis values are unsigned integers in the
  4466. range 0 - 65535.
  4467.  
  4468. Hysteresis values are expressed in terms of the
  4469. hysteresis value, in X,Y coordinate system units,
  4470. multiplied by 1000.
  4471.  
  4472.  
  4473. CATEGORY 129 - FUNCTION 61H
  4474. ___________________________
  4475.  
  4476. Performs no function: reserved.
  4477.  
  4478.  
  4479. CATEGORY 129 - FUNCTION 62H
  4480. ___________________________
  4481.  
  4482. Gets Touch Display Selection Mechanism method
  4483.  
  4484.  
  4485. PARAMETER PACKET FORMAT
  4486.  
  4487. None
  4488.  
  4489.  
  4490. DATA PACKET FORMAT
  4491.  
  4492. The data packet is a location in application
  4493. storage where the touch display driver will return
  4494. to the caller the touch display selection
  4495. mechanism method.  The format is as follows:
  4496.  
  4497.  
  4498.  *-----------------------------------------*
  4499.  | Field                        Length     |
  4500.  |-----------------------------------------|
  4501.  | Type                         WORD       |
  4502.  |-----------------------------------------|
  4503.  | Number of stable points      WORD       |
  4504.  |-----------------------------------------|
  4505.  | Tolerance value              WORD       |
  4506.  |-----------------------------------------|
  4507.  | Stable region length         WORD       |
  4508.  *-----------------------------------------*
  4509.  
  4510.  
  4511.  
  4512. Where
  4513.  
  4514.  
  4515.       Type
  4516.          the in which the selection detection flag (bit)
  4517.          in the status word returned in function 66H is set/reset
  4518.  
  4519.          Bit 0
  4520.            0 = Push harder (default)
  4521.            1 = Lift off
  4522.          Bit 1
  4523.            0 = First value taken
  4524.            1 = Single touch algorithm applied
  4525.          Bit 2
  4526.            0 = First value taken
  4527.            1 = Stable region algorithm active
  4528.          Bit 3-F
  4529.            0 = Reserved
  4530.  
  4531.  
  4532.       Number of stable points
  4533.  
  4534.          Value:
  4535.             0 = default
  4536.             n = # of stable points
  4537.  
  4538.       Tolerance value
  4539.             0 = default
  4540.             n = tolerance in pixels
  4541.  
  4542.       Stable region length
  4543.             0 = default
  4544.             n = region length in samples ( 0 < n < 60 )
  4545.  
  4546.  
  4547.  
  4548.  
  4549. Returns
  4550.  
  4551. None
  4552.  
  4553.  
  4554. Remarks:
  4555.  
  4556. For information on the single touch and stable
  4557. region algorithms, see under -- Heading 'BISTAL'
  4558. unknown --.
  4559.  
  4560.  
  4561. CATEGORY 129 - FUNCTION 63H
  4562. ___________________________
  4563.  
  4564. Gets the current Touch Display Event Mask
  4565.  
  4566.  
  4567. PARAMETER PACKET FORMAT
  4568.  
  4569. None
  4570.  
  4571.  
  4572. DATA PACKET FORMAT
  4573.  
  4574. The data packet is a location in application
  4575. storage where the touch display driver will return
  4576. to the caller the touch display event mask, which
  4577. controls ('masks') which type of events are to
  4578. added to the the event queue.  The format is as
  4579. follows:
  4580.  
  4581.  
  4582.  *-----------------------------------------*
  4583.  | Field                        Length     |
  4584.  |-----------------------------------------|
  4585.  | Event Mask                   WORD       |
  4586.  *-----------------------------------------*
  4587.  
  4588.  
  4589.  
  4590. Where
  4591.  
  4592.  
  4593.       Event mask
  4594.  
  4595.       Bit      Meaning
  4596.  
  4597.        0         1 = On Screen status set event
  4598.        1         1 = Touch Down event (On Screen status clear to set)
  4599.        2         1 = Lift Off event (On Screen status set to clear)
  4600.        3         1 = Selection Detection flag set event
  4601.        4         1 = Selection Detection flag clear to set event
  4602.        5         1 = Selection Detection flag set to clear event
  4603.        6-F       Reserved = 0
  4604.  
  4605.  
  4606.  
  4607. Returns
  4608.  
  4609. None
  4610.  
  4611.  
  4612. Remarks:
  4613.  
  4614.  
  4615. CATEGORY 129 - FUNCTION 64H
  4616. ___________________________
  4617.  
  4618. Gets the current Touch Display event queue size.
  4619.  
  4620.  
  4621. PARAMETER PACKET FORMAT
  4622.  
  4623. None
  4624.  
  4625.  
  4626. DATA PACKET FORMAT
  4627.  
  4628. The data packet is a location in application
  4629. storage where the touch display driver will return
  4630. to the caller the size of the touch display event
  4631. queue.  The format is as follows:
  4632.  
  4633.  
  4634.  *-----------------------------------------*
  4635.  | Field                        Length     |
  4636.  |-----------------------------------------|
  4637.  | Queue Size                   WORD       |
  4638.  *-----------------------------------------*
  4639.  
  4640.  
  4641.  
  4642. Where
  4643.  
  4644.  
  4645.       Queue Size
  4646.         indicates how many touch display events into the past
  4647.         are being stored in the event queue.
  4648.  
  4649.  
  4650.  
  4651. Returns
  4652.  
  4653. None
  4654.  
  4655.  
  4656. Remarks:
  4657.  
  4658.  
  4659. CATEGORY 129 - FUNCTION 65H
  4660. ___________________________
  4661.  
  4662. Gets the current Touch Display mouse emulation
  4663. state.
  4664.  
  4665.  
  4666. PARAMETER PACKET FORMAT
  4667.  
  4668. None
  4669.  
  4670.  
  4671. DATA PACKET FORMAT
  4672.  
  4673. The data packet is a location in application
  4674. storage where the touch display driver will return
  4675. to the caller the touch display mouse emulation
  4676. state The format is as follows:
  4677.  
  4678.  
  4679.  *-----------------------------------------*
  4680.  | Field                        Length     |
  4681.  |-----------------------------------------|
  4682.  | Emul State                   WORD       |
  4683.  *-----------------------------------------*
  4684.  
  4685.  
  4686.  
  4687. Where
  4688.  
  4689.  
  4690.       Emul state
  4691.         switch which turns mouse emulation on or off for the screen
  4692.         group.
  4693.  
  4694.          Bit      Description
  4695.  
  4696.           0       Screen group emulation
  4697.                   =0 = Emulation off, =1 = Emulation on
  4698.           1-F     Reserved
  4699.  
  4700.  
  4701.  
  4702. Returns
  4703.  
  4704. None
  4705.  
  4706.  
  4707. Remarks:
  4708.  
  4709. Calls the device dependent driver via the IDC to
  4710. get the emulation state.
  4711.  
  4712.  
  4713. CATEGORY 129 - FUNCTION 66H
  4714. ___________________________
  4715.  
  4716. Reads an event from the Touch Display event queue
  4717.  
  4718.  
  4719. PARAMETER PACKET FORMAT
  4720.  
  4721. None
  4722.  
  4723.  
  4724. DATA PACKET FORMAT
  4725.  
  4726. The data packet is a location in application
  4727. storage where the touch display driver will return
  4728. to the caller the touch display event.  The format
  4729. is as follows:
  4730.  
  4731.  
  4732.  *-----------------------------------------*
  4733.  | Field                        Length     |
  4734.  |-----------------------------------------|
  4735.  | remaining events             WORD       |
  4736.  |-----------------------------------------|
  4737.  | status                       WORD       |
  4738.  |-----------------------------------------|
  4739.  | timestamp                    WORD       |
  4740.  |-----------------------------------------|
  4741.  | x                            WORD       |
  4742.  |-----------------------------------------|
  4743.  | y                            WORD       |
  4744.  |-----------------------------------------|
  4745.  | z                            WORD       |
  4746.  *-----------------------------------------*
  4747.  
  4748.  
  4749.  
  4750. Where
  4751.  
  4752.  
  4753.       remaining events
  4754.         count of the number of events remaining in the queue besides
  4755.         this current event.  Less than or equal to queue size less one.
  4756.  
  4757.       status
  4758.         status bits pertaining to this touch display event.
  4759.  
  4760.       timestamp
  4761.         relative time at which event occurred in milliseconds.
  4762.  
  4763.       x
  4764.         horizontal coordinate value of touch event
  4765.  
  4766.       y
  4767.         vertical coordinate value of touch event
  4768.  
  4769.       z
  4770.         third dimension coordinate value of touch event
  4771.  
  4772.  
  4773.  
  4774.  
  4775. Returns
  4776.  
  4777. None
  4778.  
  4779.  
  4780. Remarks:
  4781.  
  4782. Bit definitions of the event status are identical
  4783. to those of the event mask (see also IOCtl's 53H
  4784. and 63H).
  4785.  
  4786. Events are placed in the event queue which have at
  4787. least one status bit in common with the current
  4788. event mask.  For instance, if the event mask has
  4789. bits 1,2 and 3 set, only events which have either
  4790. the status bit for Touch Down (bit 1), Lift Off
  4791. (bit 2) or Selection Detection (bit3) set (or any
  4792. combination thereof) will be placed in the event
  4793. queue to be read by this function.
  4794.  
  4795. For IBM PS/2 8516 Touch Display, the z value is
  4796. proportional to the force applied.
  4797.  
  4798. The 'Remaining events returned' value gives this
  4799. function the equivalent capability as a 'Get
  4800. Number of Queue Elements' type function, except
  4801. that with one function call the number of
  4802. remaining events is not subject to any uncertainty
  4803. that would arise with two separate calls (one to
  4804. read the data, the other to read how many events
  4805. remained) where events could arrive in between
  4806. making the calls.
  4807.  
  4808.  
  4809. Virtual Touch Driver Architecture
  4810.  
  4811. OBJECTIVES
  4812. __________
  4813.  
  4814. Applications that support IBM PS/2 8516 Touch
  4815. Display  in the DOS environment shall do so via
  4816. the INT7Fh API described below.  Applications that
  4817. use INT15h AH=C2h AL=10h to AL=26h BIOS calls or
  4818. those that talk directly to the 8042 device
  4819. hardware will not be supported.
  4820.  
  4821.  
  4822. INT 7FH SUPPORT
  4823. _______________
  4824.  
  4825. This will be provided directly by the Virtual
  4826. Touch Driver (VTD), using a standard VDM software
  4827. interrupt hook.  This support is essentially the
  4828. same as that provided in OS/2 1.2/3 versions of
  4829. the Device Independent Touch Driver, but is
  4830. re-written to run in protected mode, which allows
  4831. it to share code in all VDM's, as well as
  4832. virtualising all the hardware dependent features
  4833. that the INT7Fh interface provides (changing
  4834. thresholds etc.).
  4835.  
  4836. Note, however, that only DOS sessions running full
  4837. screen can obtain full touch XYZ data, windowed
  4838. DOS sessions running under PM being restricted to
  4839. emulated mouse data.  A DOS touch application
  4840. which is started as full screen will stop
  4841. receiving touch data if it is switched to a
  4842. window, and then start receiving data again if it
  4843. switched back to full screen.  Conversely, a DOS
  4844. touch application which is started in a window,
  4845. will not receive data until it is switched to full
  4846. screen, and so on.
  4847.  
  4848. This is the default mode of operation: for those
  4849. applications that insist on being able to access
  4850. full touch x,y,z data in a DOS window, the DOS
  4851. property 'Touch: exclusive to a window' can be
  4852. turned on.  This effectively turns mouse emulation
  4853. off, and gives all the touch x,y,z data directly
  4854. to a window.
  4855.  
  4856.  
  4857. INT7FH SOFTWARE INTERRUPT AND FUNCTION TABLE CALL
  4858. HANDLING
  4859.  
  4860. Following is the sequence of events when a real
  4861. mode program issues a software interrupt that has
  4862. been hooked by a VDD:
  4863.  
  4864. o   At create time, VDD installs interrupt vector
  4865.     hook (InstallHookVect())
  4866.  
  4867. o   Interrupt vector table gets patched with
  4868.     address A
  4869.  
  4870. o   Address A points to an illegal real mode
  4871.     instruction (ARPL)
  4872.  
  4873. o   Software interrupt causes transfer to address
  4874.     A
  4875.  
  4876. o   Execution of the ARPL located there
  4877.     instruction causes a trap
  4878.  
  4879. o   OS/2 fields this trap
  4880.  
  4881. o   ??? OS/2 looks into a list of procs that are
  4882.     registered for this trap via InstallHookVect
  4883.     and calls each one in turn
  4884.  
  4885. o   Hook procs get passed pointer to Client
  4886.     Register Frame
  4887.  
  4888. o   Hook procs process call based on registers
  4889.     passed in CRF
  4890.  
  4891. o   If Hook procs int then does VDHPopInt() (fills
  4892.     return CS:IP in CRF)
  4893.  
  4894. o   Hook procs returns TRUE if its int else FALSE
  4895.  
  4896. o   ??? OS/2 calls next in chain if FALSE else
  4897.     returns to CS:IP as filled in in CRF.
  4898.  
  4899. With IBM PS/2 8516 Touch Display, the interface to
  4900. device driver is via a call table, the address of
  4901. which the application obtains by issuing INT7F
  4902. with AX=ABCDh and BX=0h.  Once it has obtained the
  4903. call table address (CTA), it then calls the
  4904. individual function it requires by calling the
  4905. address at (CTA) + 4*(FN-1) where FN is the
  4906. required device driver function number.
  4907.  
  4908. This cannot be done in the above scheme, as calls
  4909. cannot be made directly from the real mode app to
  4910. the protected mode VDD.
  4911.  
  4912. The mouse INT33 driver has a related problem, in
  4913. that it has a BASIC entry point located 2 bytes
  4914. forward from the actual INT33 vector address
  4915. (first instruction of the INT33 handler is a jump
  4916. over the BASIC entry point code).  A BASIC
  4917. application would therefore obtain address A and
  4918. then call (address A + 2) which could be anything.
  4919.  
  4920. To resolve this, the VDD has to have a real mode
  4921. portion which has a software interrupt handler
  4922. similar to that provided by the real DOS driver.
  4923. The address A is then replaced by the address of
  4924. this handler (address B) by the VDD at create
  4925. time, as well as saving Address A in the real mode
  4926. portion.
  4927.  
  4928. For the particular case of the IBM PS/2 8516 Touch
  4929. Display driver, the call table must also be part
  4930. of the real mode portion, enabling calls to its
  4931. entries to be made directly by real mode apps,
  4932. with the interrupt handler setting the address of
  4933. the table in ES:BX as in the real DOS driver,
  4934. before calling address A. If the handler received
  4935. a call which did not belong to it (AX !=ABCDh)
  4936. then it would call address A directly.
  4937.  
  4938. The entries in the call table then consists of a
  4939. common call into a 'router'.  The router would
  4940. determine the function number from the address
  4941. from which it was called, and then set up the
  4942. registers appropriately before calling address A.
  4943.  
  4944.  
  4945. ------------------------------------------------------------------------------
  4946.  
  4947.              REAL                         PROTECTED
  4948.                               |
  4949.               Interrupt       |
  4950.               vector table    | *->ARPL-->OS2-*
  4951.                               | |  *------<---*          Hook proc 1
  4952.              *-----------*  *---* *V---------*   *---->*-----------*
  4953.              |           |  | |   | ------- -+---* <*  |           |
  4954.              |           |  | |   | ------- -+---*  |  |           |
  4955.              |           |  | |   |    .     |<* |  |  |           |
  4956.              |           |  | |   |    .     | | |  |  |           |
  4957.              |           |  | |   | -------  | | |  |  |           |
  4958.              |           |  | |   *----------* | |  |  |           |
  4959.              |-----------|  | |                | |  |  |           |
  4960.   INT 7F -- *< address B |  | |    list of     | |  |  |           |
  4961.             ||-----------|  | |    Installed   | |  *-<*-----------*
  4962.             ||           |  | |    IntHook's   | |
  4963.             |*-----------*  | |                | |       Hook proc 2
  4964.             |               | |                | *---->*-----------*
  4965.             V               A |                |       |           |
  4966.             |               | |                |       |           |
  4967.   Router -->|*-----------*  | |                |       |           |
  4968.             ||-----------|  | |                |       |           |
  4969.             || address A |->| |                |       |           |
  4970.             ||-----------|  | |                |       |           |
  4971.             ||           |<*| |                |       |           |
  4972.   Int 7F -->||-----------| || |                |       |           |
  4973.   handler   *>           | || |                *---<---*-----------*
  4974.              |           | || |
  4975.              |           | || |
  4976.              |        ->-+-+* |
  4977.   Int 7F     |-----------| |  |
  4978.   jump       |  ------- -+-*  |
  4979.   table      |  -------  |    |
  4980.              |  -------  |    |
  4981.              |     .     |    |
  4982.              |     .     |    |
  4983.              |     .     |    |
  4984.              |  -------  |    |
  4985.              *-----------*    |
  4986.                               |
  4987.  
  4988.  
  4989.  
  4990.  
  4991. ------------------------------------------------------------------------------
  4992. Figure 4. Software interrupt and INT7F call table.  route from real mode app
  4993.           to protected mode VDD handler
  4994.  
  4995. PTD - VTD INTERFACE
  4996. ___________________
  4997.  
  4998. This interface is very similar to the PMD - VMD
  4999. interface, except that is passes absolute touch
  5000. x,y,z,status data information instead of mouse
  5001. row,col,status data.
  5002.  
  5003. The PTD is aware at all times which session owns
  5004. the touch device:  when this is a foreground VDM,
  5005. it notifies the VTD of the touch events.  These
  5006. are then immediately buffered in the VTD.  The VTD
  5007. then processes the event by updating the INT7Fh
  5008. data structures for the foreground VDM, as well as
  5009. handling the touch event user subroutine if one is
  5010. registered (see below).
  5011.  
  5012. Note that the specific case of the Presentation
  5013. Manager session is handled differently in the case
  5014. of the mouse, where the event is sent to the PM
  5015. single queue by the PMD, whence PM notifies the
  5016. VMD whenever the mouse pointer is over a windowed
  5017. VDM (and also performs coordinate conversion on
  5018. behalf of the windowed VDM).  Note also if an
  5019. alternate mouse coordinate system is set up in the
  5020. VDM, the VMD must discard any events posted by PM
  5021. that fall outside the coordinate system but are
  5022. otherwise within the VDM window.
  5023.  
  5024. Prescott and its VTD does not have any such
  5025. relationship set up between itself and PM (nor is
  5026. there any architected mechanism for it to do so,
  5027. as the single queue only supports keyboard and
  5028. mouse events).  This is one problem that prevents
  5029. the VTD from providing full touch data for
  5030. windowed VDM's (or indeed for supporting the
  5031. TdiXXX API properly for VIO windows).  When a
  5032. touch event is received while in the PM session,
  5033. the PTD can only handle the event as though it
  5034. were a normal full screen OS/2 session:  in other
  5035. words the event passes through the device monitor
  5036. chain before being buffered in a PTD queue.  This
  5037. is because the PTD has no information regarding
  5038. the arrangement of the PM desktop, location and
  5039. size of windowed DOS sessions etc. to allow it to
  5040. directly inform the VTD of the event (correctly
  5041. tagged with the target VDM handle and coordinate
  5042. converted).
  5043.  
  5044.  
  5045. EVENT NOTIFICATION
  5046.  
  5047. Each time the VTD is notified of a touch event, it
  5048. may have to notify a VDM user subroutine.  This
  5049. will depend on (a) whether the VDM has a user
  5050. subroutine registered via INT7Fh and (b) whether
  5051. the call mask conditions match the event.
  5052.  
  5053. The calling of the user subroutine is done by
  5054. simulating an interrupt into the VDM.  An
  5055. interrupt service routine (in the VTD) is loaded
  5056. into each VDM at create time.  This routine
  5057. services the interrupt (PopInt, ClearIRR, issues
  5058. SendVEOI, PushRegs), then sets up a Client
  5059. Register Frame containing the appropriate values
  5060. of the registers and then performs a
  5061. VDHPushFarCall to the user subroutine.  It also
  5062. arms a return hook procedure to get control after
  5063. the user subroutine has completed.  When the
  5064. context of the VDM next becomes current, it
  5065. executes the user subroutine, and when the return
  5066. hook procedure gets control back it just does a
  5067. PopRegs.
  5068.  
  5069. The interrupt number chosen for simulation is the
  5070. hardware interrupt being used by the PTD.  For IBM
  5071. PS/2 8516 Touch Display, this will be IRQ12, the
  5072. same as the PS/2 mouse, unless we make it
  5073. different (the problem is then deciding on what
  5074. interrupt number can be used, without stepping on
  5075. the toes of some other VDD).
  5076.  
  5077. Q. will the virtual PIC be able to handle
  5078. interrupt simulations on the same interrupt (74H)
  5079. separately for the VMD and VTD?
  5080.  
  5081. A. yes, but it requires that IRQ12h/INT74h is
  5082. handled as a shared interrupt in the virtual
  5083. device drivers which simulate and service this
  5084. interrupt.
  5085.  
  5086. So IBM PS/2 8516 Touch Display and the PS/2 mouse
  5087. can simulate and service their own interrupts
  5088. separately while using the same IRQ12h/INT74h.
  5089.  
  5090.  
  5091. Algorithms to improve touch selection
  5092.  
  5093. In addition to the straightforward method for
  5094. setting the selection detection flag on push
  5095. harder or lift off, where the 'snapshot' x,y value
  5096. when crossing a given z threshold is used
  5097. directly, further processing of the x,y,z data
  5098. packets can be brought into play to enhance the
  5099. repeatability and accuracy of the x,y report.
  5100.  
  5101. (these improved methods of selection detection
  5102. were introduced from DOS driver level 0.9q
  5103. onwards).
  5104.  
  5105. The data processing algorithms are:
  5106.  
  5107. 1.  Single touch algorithm
  5108.  
  5109. 2.  Stable region algorithm (also called 'Back in
  5110.     the stack' algorithm)
  5111.  
  5112.     Acknowledgement:
  5113.  
  5114. ------------------------------------------------------------------------------
  5115.  
  5116.              REAL                         PROTECTED
  5117.                               |
  5118.               Interrupt       |
  5119.               vector table    | *->ARPL-->OS2-*
  5120.                               | |  *------<---*          Hook proc 1
  5121.              *-----------*  *---* *V---------*   *---->*-----------*
  5122.              |           |  | |   | ------- -+---* <*  |           |
  5123.              |           |  | |   | ------- -+---*  |  |           |
  5124.              |           |  | |   |    .     |<* |  |  |           |
  5125.              |           |  | |   |    .     | | |  |  |           |
  5126.              |           |  | |   | -------  | | |  |  |           |
  5127.              |           |  | |   *----------* | |  |  |           |
  5128.              |-----------|  | |                | |  |  |           |
  5129.   INT 7F --> | address A |--* |    list of     | |  |  |           |
  5130.              |-----------|    |    Installed   | |  *--*-----------*
  5131.              |           |    |    IntHook's   | |
  5132.              *-----------*    |                | |       Hook proc 2
  5133.                               |                | *---->*-----------*
  5134.                               |                |       |           |
  5135.                               |                |       |           |
  5136.                               |                |       |           |
  5137.                               |                |       |           |
  5138.                               |                |       |           |
  5139.                               |                |       |           |
  5140.                               |                |       |           |
  5141.                               |                |       |           |
  5142.                               |                *-------*-----------*
  5143.  
  5144.  
  5145.  
  5146. ------------------------------------------------------------------------------
  5147. Figure 3. Software interrupt handling:.  Route from real mode app to protected
  5148.           mode VDD handler
  5149.  
  5150.     These algorithms were developed at the IBM
  5151.     Thomas J. Watson Research Center by Jim Levine
  5152.     (LEVINE2 at YKTVMZ) and it is hoped that these
  5153.     implementations remain faithful to the
  5154.     original.
  5155.  
  5156.     The algorithms are activated by setting the
  5157.     appropriate bit in the selection detection
  5158.     mechanism type parameter of Function 6 'Set
  5159.     Selection Mechanism'. Only one algorithm can
  5160.     be active at any given time, in either Push
  5161.     Harder or Lift Off mode.
  5162.  
  5163. 3.  'Click locking'
  5164.  
  5165.     Click locking  was introduced primarily as a
  5166.     means by which the OS/2 Presentation Manager
  5167.     could more successfully be operated in mouse
  5168.     emulation mode, but was found to be equally as
  5169.     useful in the DOS environment.
  5170.  
  5171.  
  5172. ACCURACY OF THE X,Y REPORT
  5173.  
  5174. Touch accuracy (or lack thereof) is one of the
  5175. main contributing reasons to the need to improve
  5176. touch selection.
  5177.  
  5178. There are many factors which can affect touch
  5179. (in)accuracy.  These include:
  5180.  
  5181. o   Style of touch
  5182.  
  5183.     As the screen is being touched, from the point
  5184.     of touch down to lift off, there may be some
  5185.     appreciable movement of the reported x,y
  5186.     position even if the intention is to keep the
  5187.     point of contact stationary.  This can be
  5188.     dependent on the manner the screen is touched,
  5189.     where a rapid 'stab' at the screen can produce
  5190.     a larger variation than a slower, lighter
  5191.     touch.
  5192.  
  5193. o   On screen touch threshold
  5194.  
  5195.     Lowering the on screen touch threshold makes
  5196.     the system not only more sensitive to a touch,
  5197.     but also to external unwanted 'noise' such as
  5198.     mechanical vibration.
  5199.  
  5200. o   Filter cut off frequency
  5201.  
  5202.     Increasing the system's low pass cut off
  5203.     frequency may increase the system's
  5204.     responsiveness to fast touches, but does so at
  5205.     the expense of being able to filter out
  5206.     unwanted noise/variation/movement.
  5207.  
  5208.  
  5209. SINGLE TOUCH ALGORITHM
  5210. ______________________
  5211.  
  5212.  
  5213. BENEFITS
  5214.  
  5215. The single touch algorithm is primarily designed
  5216. to offer more consistent 'touch-down' x,y
  5217. coordinates over a wide range of applied touch
  5218. speed and pressure.
  5219.  
  5220. The single touch algorithm prevents the 'snapshot'
  5221. x,y data taken at the first point of contact being
  5222. used when the following data reports are moving
  5223. rapidly away from the initial position (for
  5224. example, because the screen has been 'poked'
  5225. giving initial inaccurate data reports).  Rather,
  5226. it ensures the the data reports have settled down
  5227. within a consistent area for a given number of
  5228. reports (the size of the area and number of
  5229. reports are determined by additional (optional)
  5230. parameters).
  5231.  
  5232. The algorithm simply check each point with its
  5233. succeeding neighbour, and if the second differs
  5234. from the first by an amount which is within the
  5235. defined tolerance, a count is incremented.  If
  5236. not, the count is set to zero.  Only when the
  5237. count has reached the defined minimum is the data
  5238. deemed to have settled and the x,y report given
  5239. with the status of 'selection detected'.
  5240.  
  5241. In the push harder mode, it is possible to touch
  5242. the screen and lift off within having satisfied
  5243. the condition and generated the 'selection
  5244. detected'.  In the lift off mode
  5245.  
  5246. The algorithm does have the drawback that as the
  5247. number of reports and tolerance parameters are
  5248. tightened, so is the requirement for more
  5249. controlled, slow and deliberate touches.  Lightly
  5250. tapping or quickly stabbing the screen are less
  5251. likely to trigger the algorithm either because of
  5252. lack of sufficient data or too much variation
  5253. within the data.
  5254.  
  5255. Because of this, it is less likely to be of use in
  5256. an untrained user/public kiosk type environment
  5257. where user frustration would probably result.  In
  5258. any event, applications designed to be used in
  5259. such environments would generally avoid the effect
  5260. of inaccuracy/repeatability by having more simply
  5261. designed screens with large, widely spaced
  5262. targets.
  5263.  
  5264.  
  5265. PSEUDOCODE
  5266.  
  5267.  
  5268.  
  5269.           If status == on-screen
  5270.              Call Update single touch x,y
  5271.              If selection method == Lift Off
  5272.                 Return()
  5273.              Else   /* must be push harder */
  5274.                 If !(sm detected flag)
  5275.                    Return()
  5276.                 Else
  5277.                    If single touch sent
  5278.                       Return()           /* only send once on transition */
  5279.                    Else                  /* this is the first time       */
  5280.                                          /* select detect has gone on    */
  5281.                       current x,y = single touch x,y
  5282.                       single touch sent = TRUE
  5283.                       Return()
  5284.                    Endif
  5285.                 Endif
  5286.              Endif
  5287.           Else
  5288.              If status == touch down
  5289.                 single touch x,y = current x,y
  5290.                 sm detected flag = single touch sent = FALSE
  5291.                 count = RESET_VALUE
  5292.                 Return()
  5293.              Else
  5294.                 If (selection method == Lift Off) && (status == lift-off)
  5295.                    Call Update_Single_Touch_xy()
  5296.                    current x,y = single touch x,y
  5297.                    Return()
  5298.                 Endif
  5299.              Endif
  5300.           Endif
  5301.  
  5302.  
  5303.  
  5304.           Procedure Update_Single_Touch_xy()
  5305.              If Modulus( Current x,y - single touch x,y ) < tolerance
  5306.                 Single Touch x,y = (Single Touch x,y + Current x,y ) / 2
  5307.                 count--
  5308.                 If (count==0) set sm detect flag
  5309.              Else
  5310.                 Single Touch x,y = current x,y
  5311.                 count = RESET_VALUE
  5312.              Endif
  5313.           Endproc
  5314.  
  5315.  
  5316.  
  5317. 'BACK IN THE STACK' ALGORITHM
  5318. _____________________________
  5319.  
  5320.  
  5321. BENEFITS
  5322.  
  5323. The 'Back in the Stack' (BIST) algorithm provides
  5324. for detailed selection of an item (down to pixel
  5325. level at 640 x 480 resolution) even in the
  5326. presence of varying x,y data packets when the
  5327. selection needs to be made.
  5328.  
  5329. For example, it may be relatively easy to adjust
  5330. the touch contact so that the required (small)
  5331. item is identified, but then much more difficult
  5332. to actually perform the selection, either by
  5333. lifting off or pressing harder, without
  5334. involuntarily moving the x,y position and thereby
  5335. selecting the wrong item.
  5336.  
  5337. The BIST algorithm gets round this by exploiting
  5338. the natural way in which such a selection would be
  5339. made:  usually the touch contact position is
  5340. adjusted until the required item is identified,
  5341. hold momentarily, then the selection gesture made.
  5342.  
  5343. Thus, instead of taking the snapshot x,y position
  5344. at the time the gesture is recognised (the z value
  5345. exceeds the push harder threshold, or a lift off
  5346. event status is reported), 'looks back' into a
  5347. circular buffer (a form of stack containing the N
  5348. most recent x,y,z reports, where the oldest
  5349. contents are continually being overwritten by the
  5350. newest) to find the plateau region where the touch
  5351. was held on the required item.
  5352.  
  5353. Having found a plateau region of sufficient
  5354. length, the x,y values of the data report
  5355. containing the 'selection detected' status are
  5356. taken from the average of the x,y values of the
  5357. reports in the stable region.
  5358.  
  5359. In this way, the x,y value reported is relatively
  5360. immune to any variations in x,y which take place
  5361. between finding the item, and then trying to
  5362. select it.
  5363.  
  5364. The following figure illustrates the technique:
  5365.  
  5366. ------------------------------------------------------------------------------
  5367.  
  5368.     |   *
  5369.  C  |    **       *
  5370.  o  |      *       *    *           *
  5371.  o  |      *     *  **** ***** * *** *
  5372.  r  |        *  *             * *     *
  5373.  d  |          *                       *
  5374.  i  |         *                         *
  5375.  n  |                                    * *
  5376.  a  |                                       *
  5377.  t  |                                        *
  5378.  e  |                                         *  <--- Lift off
  5379.     |
  5380.     *-------------------------------------------------------------
  5381.  
  5382.         |          |                |                         Time ->
  5383.          Manipulation   Hold on item  Select item by
  5384.          to identify    to select     lift off
  5385.          item
  5386.  
  5387.  
  5388. ------------------------------------------------------------------------------
  5389. Figure 5. Back in the Stack algorithm.  Finding the selection plateau region
  5390.  
  5391. Note the typical way in which the x,y position
  5392. tends to 'slide' away from the required selection
  5393. point (and therefore make selection of the
  5394. required item impossible by normal means) as the
  5395. selection gesture is made by releasing the touch
  5396. force.
  5397.  
  5398. Without the BIST algorithm, the smallest size of
  5399. selection item would be restricted to
  5400. approximately twice the anticipated x,y movement
  5401. from selection to lift off.
  5402.  
  5403. What the BIST algorithm provides, therefore, is
  5404. the ability to track back through a short history
  5405. of the data to determine that a selection point
  5406. was being held just prior to lift off.  In this
  5407. way, the selection item size is limited by the
  5408. amount of x,y jitter while a touch is being held
  5409. steady.
  5410.  
  5411. An alternative use for the BIST algorithm is to
  5412. provide a means for cancelling a selection when it
  5413. would otherwise be inevitable: this is the case
  5414. where the selection method is lift off, and there
  5415. is no 'dead area' on the screen for the user to
  5416. move to and lift off without selecting anything.
  5417. Wherever the user decides to lift off, they will
  5418. select something.  What, then, do they do if they
  5419. touch the screen by accident, or touch and then
  5420. decide to cancel the operation?
  5421.  
  5422. In either case, all the user has to do is to lift
  5423. off in a long, exaggerated 'swiping' motion.  What
  5424. this does is to fill up the stack/circular buffer
  5425. with continuously varying data so that there is no
  5426. plateau region for the algorithm to find.
  5427.  
  5428. Detailed selection in the manner described, and/or
  5429. the method of 'not-selecting' would, of course, be
  5430. restricted to experienced users as both are
  5431. operations which require a small degree of
  5432. practice, and in the case of the ability to
  5433. 'not-select', knowledge that the facility existed
  5434. at all (since a full screen select sensitive
  5435. application screen would presumably leave no room
  5436. for help instructions...).
  5437.  
  5438.  
  5439. PSEUDOCODE
  5440.  
  5441.  
  5442. Main routine
  5443.  
  5444.           If status == on-screen
  5445.              put x,y into circular buffer
  5446.              If selection method == Lift Off
  5447.                 Return()
  5448.              Else     /* must be push harder */
  5449.                 If ( z < Push Harder Threshold )
  5450.                    Return()
  5451.                 Else
  5452.                    Call Send_Stable_Data
  5453.                 Endif
  5454.              Endif
  5455.           Else
  5456.              If status == touch-down
  5457.                 flush circular buffer
  5458.                 clear flags
  5459.              Else     /* lift-off */
  5460.                 If selection method == Lift Off
  5461.                    Call Send_Stable_Data()
  5462.                 Endif
  5463.           Endif
  5464.  
  5465.  
  5466.  
  5467. Send_stable_data
  5468.  
  5469.           Procedure Send_Stable_Data
  5470.              If already sent
  5471.                 Return()
  5472.              Else
  5473.                 Call Check_Buffer_For_Stable_Region()
  5474.                 If Stable Region Detect flag
  5475.                    Current x,y = Stable x,y
  5476.                    Set flags
  5477.                    Return()
  5478.                 Else
  5479.                    Return()
  5480.                 Endif
  5481.              Endif
  5482.           EndProc
  5483.  
  5484.  
  5485. Check_Buffer_For_Stable_Region
  5486.  
  5487.           Procedure Check_Buffer_For_Stable_Region
  5488.              Stable Ref Point x,y = Buffer Head x,y
  5489.              Reset count, buffer index
  5490.              While points left in buffer
  5491.                 Get buffer x,y
  5492.                 If ( Modulus( buffer x,y - Stable Ref Point x,y ) < Tolerance
  5493.                    count ++
  5494.                    If count >= Stable Region Size
  5495.                       Stable Region x,y = Average x,y over stable region
  5496.                       Set Stable Region Detect flag
  5497.                       Return()
  5498.                    Endif
  5499.                 Else
  5500.                    Stable Ref Point x,y = current x,y
  5501.                    Reset count, buffer index
  5502.                 Endif
  5503.              EndWhile
  5504.           Endproc
  5505.  
  5506.  
  5507. CLICK LOCKING
  5508. _____________
  5509.  
  5510. Click locking is the process by which the touch
  5511. (x,y) coordinate gets locked onto a value before
  5512. being sent to the system as emulated mouse data.
  5513.  
  5514. Note:  Click locking only affects touch data when
  5515.        it is sent as emulated mouse data and does
  5516.        not interfere with the normal use of an IBM
  5517.        PS/2 mouse if one is attached to the IBM
  5518.        PS/2 Touch Display 8515, or the data sent
  5519.        in full touch pointing mode.
  5520.  
  5521. Click locking is performed because some actions
  5522. which are done with the mouse button being clicked
  5523. require that little movement of the mouse pointer
  5524. itself should take place.  Click locking makes the
  5525. action of double clicking using the touch display
  5526. easier as it removes the need to maintain the
  5527. touch position at exactly the same point between
  5528. clicks.
  5529.  
  5530. Prime examples of this can be found in OS/2
  5531. Presentation Manager:
  5532.  
  5533. o   Clicking on an icon to bring up the system
  5534.     menu, or double clicking to activate the
  5535.     window.
  5536.  
  5537.     The first of these actions, when attempted
  5538.     with the touch display emulating the mouse can
  5539.     occasionally result in the icon simply moving
  5540.     a few pixels, as the PM shell will
  5541.     misinterpret the 'click down with associated
  5542.     movement' as a drag operation to move the
  5543.     icon.  This is because it decides that if the
  5544.     movement is more than a few pixels it must be
  5545.     click with drag rather than a simple click.
  5546.  
  5547.     Thus even a single click action is sometimes
  5548.     unsuccessful.  Even less successful will be
  5549.     the double click action: even if the first
  5550.     click can be done without causing the icon to
  5551.     move, the second click must be done at the
  5552.     same position (actually PM allows a small
  5553.     movement of 6 pixels in the x direction and 8
  5554.     pixels in the y direction).  With a great deal
  5555.     of practice, this condition can be met, but
  5556.     perhaps with only a 20% success rate (tip: for
  5557.     least x,y movement the force variation should
  5558.     be kept to a minimum.  In other words, don not
  5559.     press harder than necessary to achieve the
  5560.     button down threshold, and do not lift off
  5561.     completely between clicks, rather just release
  5562.     sufficiently to go below the button up
  5563.     threshold).  The normal outcome of such an
  5564.     attempted action is that the icon will move
  5565.     and/or the system menu will appear.
  5566.  
  5567.     It is this difficulty, of maintaining the x,y
  5568.     position while button clicking, that click
  5569.     locking attempts to remedy.  While being
  5570.     mainly applicable to PM, the technique is also
  5571.     useful in the DOS 4.0 shell, or indeed any
  5572.     application (usually in graphics mode) that
  5573.     uses the mouse.
  5574.  
  5575. The three click locking options that may be chosen
  5576. are:
  5577.  
  5578.     No click locking
  5579.     Single click locking
  5580.     Double click locking
  5581.  
  5582.  
  5583. NO CLICK LOCKING
  5584.  
  5585. Using this option, click locking may be turned off
  5586. altogether, in which case the system sees the
  5587. touch coordinates directly as mouse coordinates.
  5588.  
  5589.  
  5590. SINGLE CLICK LOCKING
  5591.  
  5592. This option locks the (x,y) coordinates as soon as
  5593. the button down threshold has been exceeded.  All
  5594. subsequent touch coordinates will then be reported
  5595. to the system with this (x,y) value when sent as
  5596. emulated mouse data.
  5597.  
  5598. Normal reporting of (x,y) coordinates will resume:
  5599.  
  5600. o   After the click lock time has been exceeded.
  5601.  
  5602. o   If the touch coordinate moves outside the
  5603.     click lock area
  5604.  
  5605. o   If the touch is removed from the screen.
  5606.  
  5607.  
  5608. DOUBLE CLICK LOCKING
  5609.  
  5610. This option is the same as single click locking,
  5611. except that the conditions for normal reporting of
  5612. (x,y) data are:
  5613.  
  5614. o   After the click lock time has been exceeded.
  5615.  
  5616. o   If the touch coordinate moves outside the
  5617.     click lock area
  5618.  
  5619. o   If the button down threshold is exceeded for a
  5620.     second time, the touch having been taken below
  5621.     the button up threshold in the interim period.
  5622.  
  5623. The third condition enables the (x,y) coordinates
  5624. of two successive touches to be locked at the some
  5625. value.  Note that the touch need not be removed
  5626. from the screen completely, it being sufficient to
  5627. just go below the button up threshold.
  5628.  
  5629.  
  5630. CLICK LOCK AREA
  5631.  
  5632. This value determines the size of one side of a
  5633. square which defines the click lock area.  The
  5634. centre of the square is located at the (x,y)
  5635. position at which the coordinates become locked.
  5636. When the touch coordinate moves outside the click
  5637. lock area, normal (x,y) reporting is resumed.
  5638.  
  5639. The value is in pixel units, and will therefore
  5640. vary with screen resolution if a click lock area
  5641. of a given physical dimension is required.
  5642.  
  5643. A large value will make double clicking at a point
  5644. very easy, but at the expense of making immediate
  5645. minor adjustment/close manipulation by dragging
  5646. slightly more cumbersome.
  5647.  
  5648.  
  5649. CLICK LOCK TIME
  5650.  
  5651. This value determines the time which is allowed to
  5652. elapse from the time the coordinates first become
  5653. locked to when normal (x,y) reporting is resumed.
  5654.  
  5655. A large value will make double clicking a more
  5656. unhurried process, but at the expense of making
  5657. immediate minor adjustment/close manipulation by
  5658. dragging slightly more cumbersome.
  5659.  
  5660.  
  5661. PSEUDOCODE
  5662.  
  5663.  
  5664.           Constants:
  5665.                      x_limit  = limit of allowed movement in x direction
  5666.                      y_limit  = limit of allowed movement in y direction
  5667.                      timeout  = limit of time between successive clicks
  5668.                      click_type = number of successive clicks to lock over
  5669.  
  5670.           Variables:
  5671.                      sd_count = number of successive clicks being locked over
  5672.                      sd_time  = system time at which timeout will occur
  5673.                      sd_x     = initial button down x position
  5674.                      sd_y     = initial button down y position
  5675.                      x        = current reported x position
  5676.                      y        = current reported y position
  5677.  
  5678.           Initial state:
  5679.                      sd_count = 0
  5680.  
  5681.  
  5682.           On entry to the procedure the x,y values are set to the current
  5683.           x,y coordinate report.  A bit in a status word (selection
  5684.           detection bit) reflects the binary state of the emulated mouse
  5685.           button (1= button down 0= button up).
  5686.  
  5687.           /* check if click locking active and still valid:
  5688.              if so lock the coordinate
  5689.              else reset the process
  5690.           */
  5691.  
  5692.           If sd_count != 0
  5693.  
  5694.              /* if click locking currently active */
  5695.  
  5696.              If sd_time > current time
  5697.                 && modulus(x - sd_x) < x_limit
  5698.                 && modulus(y - sd_x) < y_limit
  5699.  
  5700.                 /* if not timed out and within lock area */
  5701.                 /* force current x,y position to first click position */
  5702.                 x = sd_x
  5703.                 y = sd_y
  5704.  
  5705.                 If button going up
  5706.                    && (sd_count >= click_type)
  5707.  
  5708.                    /* if the 'button' is being released and required */
  5709.                    /* number of clicks reached */
  5710.                    sd_count = 0       /* reset the click locking process */
  5711.                 Endif
  5712.  
  5713.              Else
  5714.  
  5715.                 /* timed out or moved outside lock area: reset click locking */
  5716.                 sd_count = 0
  5717.  
  5718.              Endif
  5719.           Endif
  5720.  
  5721.           /* check if button going down to increment sd_count,
  5722.              thereby starting click locking if it was previously 0
  5723.              or incrementing towards the required number of clicks if not
  5724.           */
  5725.  
  5726.           If button going down
  5727.  
  5728.              /* re-initialise timeout time on each button down */
  5729.  
  5730.              sd_time = current time + timeout
  5731.  
  5732.              If sd_count == 0
  5733.  
  5734.                 /* if this is the first button down, set the lock coordinates
  5735.                    to the current x,y values */
  5736.  
  5737.                 sd_x = x
  5738.                 sd_y = y
  5739.  
  5740.              Endif
  5741.  
  5742.              sd_count++         /* increment click count */
  5743.  
  5744.           Endif
  5745.  
  5746.