Add support for pointer barrier events

Signed-off-by: Jasper St. Pierre <jstpierre@mecheye.net>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

1 files changed, 188 insertions, 0 deletions

diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index c018026..b1c29c0 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -14,6 +14,7 @@ Authors:
 History 
 -------
 
+- v2.3, December 2012: Pointer barrier events added
 - v2.2, March 2012: Multitouch support added
 - v2.1, December 2011: new raw event behaviour, smooth scrolling support
   added
@@ -57,6 +58,10 @@ Changes in version 2.2
 
 - Multitouch support added
 
+Changes in version 2.3
+----------------------
+
+- Pointer barrier events added
 
 //                            ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -551,6 +556,54 @@ window set has been reached, the event is delivered:
 Emulated pointer events will have the PointerEmulated flag set. A touch
 event that emulates pointer events has the TouchEmulatingPointer flag set.
 
+
+[[barrier-events]]
+Pointer barrier events
+^^^^^^^^^^^^^^^^^^^^^^
+If a master pointer moves against a pointer barrier blocking movement in
+that pointer's direction, the movement of the pointer is clamped to the x or
+y coordinate of the barrier, whichever applies. For a description of pointer
+barriers and barrier creation and destruction see the XFixes protocol
+specification v 5.0 or later.
+http://cgit.freedesktop.org/xorg/proto/fixesproto/plain/fixesproto.txt
+
+A pointer hitting a blocking barrier creates a new barrier event sequence,
+identified by a unique event ID. A new event ID is assigned when the pointer
+first hits a barrier. Subsequent movements against or along the pointer
+barrier are assigned the same event ID. The event generated by the pointer
+leaving the barrier, or being released by a client request, is the last
+event with this event ID. Any future movements of this device blocked by
+this barrier will be assigned a new event ID.
+
+Pointer barrier events are delivered exclusively to the client that created
+the barrier, and to the window specified in the CreatePointerBarrier
+request (the "barrier window"). A pointer barrier blocks pointer movement
+regardless of whether its window is mapped and/or viewable. If the pointer
+barrier window is destroyed, the pointer barrier remains blocking but a
+client will not receive further events.
+
+If a device is actively grabbed by a client or a passive grab activated
+for this client, and the pointer moves against a pointer barrier created by
+this client and the grab-window is the barrier window, that client will
+receive pointer barrier events if:
+- owner-events is true or false and the grab's event mask includes
+  pointer barrier events, or
+- owner-events is true and the client has selected for barrier events on the
+  barrier window.
+
+If the grab-window is not the barrier window, the client will receive events
+if:
+- the client has selected for barrier events on the barrier window.
+
+If the barrier is not owned by this client, no barrier events are sent to
+this client. The client owning the barrier will receive events if:
+- the client has pointer barrier events selected on the window associated
+  with the pointer barrier
+
+The BarrierDeviceIsGrabbed flag is set whenever a pointer barrier event is
+generated while the device is actively grabbed by any client or a passive
+grab has activated for this device prior to the event.
+
 [[glossary-notations]]
 Notations used in this document
 -------------------------------
@@ -1940,6 +1993,48 @@ giving the number of trailing unread bytes in the stored property. If
 delete is True and the bytes_after is zero, the property is also
 deleted from the device, and a XIPropertyNotify event is generated on
 the device.  
+
+[[requests-xi23]]
+Requests introduced in version 2.3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[requests-barrierreleasepointer]]
+XIBarrierReleasePointer
+^^^^^^^^^^^^^^^^^^^^^^^
+    ┌───
+        XIBarrierReleasePointer
+            num_items:       CARD32
+            ▶
+            data:            LISTofBARRIERRELEASEINFO
+    └───
+
+    BARRIERRELEASEINFO { deviceid: DEVICEID,
+                         barrier:  Barrier,
+                         eventid: CARD32 }
+
+Release a pointer currently blocked by a barrier. In the future, movement of
+this pointer against the barrier will not be blocked.
+
+        deviceid
+            The device currently being blocked by a barrier
+        barrier
+            The barrier currently blocking the device
+        eventid
+            The unique event ID assigned to this barrier event sequence
+
+If the barrier given does not currently block this device, or the eventid
+is invalid, this request does nothing.
+
+Releasing a pointer barrier is only valid during one barrier event sequence,
+and only applies to the next movement of this device against this barrier.
+If the pointer moves away from the barrier following a
+XIBarrierReleasePointer request, the release request is discarded. In the
+future, if the pointer moves against the barrier again, a new eventid is
+assigned and the client must re-issue the XIBarrierReleasePointer request.
+
+If the device is not a master pointer device, a BadDevice error results.
+If the barrier does not name a valid barrier, a BadValue error results.
+
      
 [[events]]
 Events
@@ -1984,6 +2079,11 @@ Version 2.2:
         - RawTouchUpdate
         - RawTouchEnd
 
+Version 2.3:
+
+        - BarrierHit
+        - BarrierLeave
+
 All events have a set of common fields specified as EVENTHEADER.
 
 
@@ -2434,6 +2534,94 @@ is now the owner of the touch sequence specified by touchid.
     flags
         A bitmask of flags for this event.
 
+[[events-xi23]]
+Events introduced in version 2.3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[events-barrierevent]]
+BarrierEvent
+^^^^^^^^^^^^
+    ┌───
+        BarrierEvent
+            EVENTHEADER
+            eventid:                    CARD32
+            root:                       Window
+            event:                      Window
+            barrier:                    Barrier
+            dtime:                      CARD32
+            flags:                      SETofBARRIERFLAGS
+            sourceid:                   DEVICEID
+            root_x:                     FP1616
+            root_y:                     FP1616
+            dx:                         FP3232
+            dy:                         FP3232
+    └───
+
+    BARRIERFLAGS { PointerReleased, DeviceIsGrabbed }
+
+A BarrierEvent indicates interaction between a barrier and a pointer device.
+If the event type is BarrierHit, pointer movement has been blocked by a
+barrier. If the event type is BarrierLeave, a pointer previously blocked
+by a barrier has moved away from that barrier, or has moved
+through the blocking barrier following an earlier XIBarrierReleasePointer
+request.
+
+    eventid
+       The unique event ID for this barrier event sequence.
+    root
+    event
+        The root window or barrier window, respectively. The barrier window
+        is always the drawable specified in in the CreatePointerBarrier request.
+    barrier
+        The barrier blocking pointer movement.
+    dtime
+        The relative time in milliseconds between the last event and this
+        event.
+    flags
+        A set of flags that apply to this barrier event
+        PointerReleased:
+           The pointer has moved through the barrier following a
+           XIBarrierReleasePointer request (BarrierLeave only).
+        DeviceIsGrabbed:
+           The pointer device that generated this event is currently
+           grabbed.
+    sourceid
+        The source device that originally generated the event.
+    root_x
+    root_y
+        The position of the pointer in screen coordinates (16.16 fixed
+        point), after being constrained by barrier and/or screen extents.
+    dx
+    dy
+        The relative movement of the pointer from its previous position to
+        the new position if pointer movement were not constrained by this
+        barrier.
+
+Root coordinates in barrier events represent the position of the cursor
+after confinement by barriers, screens and RandR output extents.
+
+Barrier event IDs are provided in the eventid field of barrier events. Its
+value is always provided in every barrier event. Event IDs are
+represented as unsigned 32-bit values and increase strictly monotonically in
+value for each new barrier event sequence, wrapping back to 0 upon reaching
+the numerical limit of IDs. The increment between two event IDs is
+indeterminate. Clients may not assume that any future barrier constraints
+will have specific event IDs. IDs are unique per device per barrier.
+
+If a pointer is actively grabbed after a barrier event sequence has
+initiated, future barrier events of this sequence continue to use the same
+eventid, but all barrier events have the DeviceIsGrabbed flag set. If the
+pointer is ungrabbed, future events of this sequence have the same eventid
+and the DeviceIsGrabbed flag is unset.
+
+The PointerReleased flag may only be set on a BarrierLeave event.
+A BarrierLeave(PointerReleased) event is generated when the pointer moves
+through the barrier following a XIBarrierReleasePointer request. The time
+between the XIBarrierReleasePointer and the BarrierLeave event thus depends
+on user input.
+A BarrierLeave(PointerReleased) event is also generated if the barrier is
+destroyed while pointer movement is constrained by the barrier. This event
+has a dx/dy of 0/0.
 
 :numbered!:
 [[xi22-usecases]]