Pointer devices
---------------

Pointer devices (usually mice) have been extended to provide additional
functionality found in more modern devices such as additional buttons and
an alternate positioning device (usually provided as a single or dual
'scroll wheel'). In order to provide these extra functions, a revised form
of the PointerV interface has been used. This builds upon the interface
declared in PRM 5a, but moves some functions away from the driver.

Presently, the kernel controls pointer movement and will handle these
extended functions. On certain OS versions the task of controlling pointer
movement may be handled by another module. This should not affect the
operation of drivers.

The operation is split into two major parts :
  * How drivers provide information to the kernel about the new features
  * How programmers access this information

In addition, a separate document details the operation of the WindowScroll
module which provides functionality for desktop tasks.

Vectors
-------
PointerV 4
=> R0 = 4 (Extended request)
   R1 = pointer type
<= R0 = -1 to indicate that the request was claimed
   R2 = signed 32 bit change in X position
   R3 = signed 32 bit change in Y position
   R4 = signed 32 bit change in X position of alternate device
   R5 = signed 32 bit change in Y position of alternate device
   R6 = mouse buttons :
           b0  Right button
           b1  Middle button
           b2  Left button
         b3-b7 May be provided at the discretion of driver

This vector reason is called by the kernel to determine the position of the
pointing device in a similar manner to that of PointerV 1 (Request). Drivers
should check the pointer type and if it matches the device being provided
details should be returned and the vector claimed. If the pointer type does
not match, the vector should be passed on.

Unlike PointerV 1 (Request), drivers should not issue KeyV requests for the
mouse buttons that they provide. This task will be performed by the kernel
based on the button state returned. Drivers wishing to support both the old
and new protocol may share code between PointerV 1 (Request) and PointerV 2
(Result) but they must ensure that registers are not corrupt unduly and that
the different mouse button processing is performed based on the request
type.

For scroll wheel-like alternate devices, the +ve Y direction should be that
for pushing the wheel 'away' from the user.


Quadrature mouse driver
-----------------------
The quadrature mouse driver ('Mouse' module) has been updated to provide
an additional device type for Stuart Tyrrell's PS2 mouse interface. This
interface functions in 'driver' mode to provide alternate device support for
single axis devices (primarily vertical scroll wheels).

Dual axis movement is presently not supported.


PS 2 mouse driver
-----------------
The PS 2 mouse driver ('PS2Driver' module) has been updated to provide
support for 'Intellimouse' and 'Intellimouse Pro' devices. These are
more commonly known as 'scroll mice' or '5 button mice' respectively.

Dual axis movement is presently not supported.


Kernel handling of extended requests
------------------------------------
The kernel will issue the above Extended request for versions of the
OS which support these new features (4.32 and later). If the call returns
unclaimed (R0 having not been set to -1), the kernel will issue PointerV 1
(Request) and defer button handling to the driver.

If the call is claimed, however, the kernel will issue KeyV events for the
buttons which have been pressed. Presently only the core three buttons
are provided for. Future versions may issue further events for additional
buttons.


Programmers interface
---------------------
In order obtain position details for the alternate scrolling device, a
new reason has been added to OS_Pointer.

SWIs
----
OS_Pointer 2
=> R0 = 2 (read alternate position)
<= R0 = signed 32bit X position of the alternate device
   R1 = signed 32bit Y position of the alternate device

This SWI returns the position of the alternate positioning device. The
device position is unbounded and thus may wrap when the limits of the
32bit representation are reached. Should the device position wrap past
a limit, it will be reset to zero. Thus, should the position exceed
either &7FFFFFFF or -&80000000 it will be reset. Clients should be aware
of this and handle such conditions appropriately.


Vectors
-------
EventV 21, 4
=> R0 = 21 (Expansion event)
   R1 = 4 (Pointer scroll event)
   R2 = signed 32bit change in X position
   R3 = signed 32bit change in Y position

This event is generated by the kernel when a scroll event is triggered by
the user. Clients which track mouse movements should monitor this event.
This allows clients to monitor either changes, or the absolute position
should they wish to. If clients wish to cause the scroll event to be ignored
they should claim the event.


Thanks
------
Thanks to Stuart Tyrrell for his feedback and support.
