[PATCH inputproto] Add pointer barrier events

Peter Hutterer peter.hutterer at who-t.net
Thu Dec 6 22:25:05 PST 2012


New events:
    XI_BarrierHit ... when a pointer moves against or along a barrier
    XI_BarrierLeave . when a pointer moves away from or through a barrier
New requests:
    XIBarrierReleasePointer ... allow movement through the barrier for the
                                next event

Co-authored-by: Jasper St. Pierre <jstpierre at mecheye.net>
Co-authored-by: Christopher James Halse Rogers <christopher.halse.rogers at canonical.com>
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 XI2.h              |  11 +++-
 XI2proto.h         |  49 +++++++++++++-
 specs/XI2proto.txt | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 245 insertions(+), 2 deletions(-)

diff --git a/XI2.h b/XI2.h
index e864b06..5a245e8 100644
--- a/XI2.h
+++ b/XI2.h
@@ -160,6 +160,11 @@
 #define XITouchPendingEnd                       (1 << 16)
 #define XITouchEmulatingPointer                 (1 << 17)
 
+/* Barrier event flags */
+#define XIBarrierPointerReleased                (1 << 0)
+#define XIBarrierDeviceIsGrabbed                (1 << 1)
+
+
 /* Touch modes */
 #define XIDirectTouch                           1
 #define XIDependentTouch                        2
@@ -199,7 +204,9 @@
 #define XI_RawTouchBegin                 22
 #define XI_RawTouchUpdate                23
 #define XI_RawTouchEnd                   24
-#define XI_LASTEVENT                     XI_RawTouchEnd
+#define XI_BarrierHit                    25 /* XI 2.3 */
+#define XI_BarrierLeave                  26
+#define XI_LASTEVENT                     XI_BarrierLeave
 /* NOTE: XI2LASTEVENT in xserver/include/inputstr.h must be the same value
  * as XI_LASTEVENT if the server is supposed to handle masks etc. for this
  * type of event. */
@@ -232,5 +239,7 @@
 #define XI_RawTouchBeginMask             (1 << XI_RawTouchBegin)
 #define XI_RawTouchEndMask               (1 << XI_RawTouchEnd)
 #define XI_RawTouchUpdateMask            (1 << XI_RawTouchUpdate)
+#define XI_BarrierHitMask                (1 << XI_BarrierHit)
+#define XI_BarrierLeaveMask              (1 << XI_BarrierLeave)
 
 #endif /* _XI2_H_ */
diff --git a/XI2proto.h b/XI2proto.h
index 9418357..4cdaa0d 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -67,6 +67,7 @@
 #define Time    uint32_t
 #define Atom    uint32_t
 #define Cursor  uint32_t
+#define Barrier uint32_t
 
 /**
  * XI2 Request opcodes
@@ -92,9 +93,10 @@
 #define X_XIDeleteProperty              58
 #define X_XIGetProperty                 59
 #define X_XIGetSelectedEvents           60
+#define X_XIBarrierReleasePointer       61
 
 /** Number of XI requests */
-#define XI2REQUESTS (X_XIGetSelectedEvents - X_XIQueryPointer + 1)
+#define XI2REQUESTS (X_XIBarrierReleasePointer - X_XIQueryPointer + 1)
 /** Number of XI2 events */
 #define XI2EVENTS   (XI_LASTEVENT + 1)
 
@@ -815,6 +817,22 @@ typedef struct {
 } xXIGetPropertyReply;
 #define sz_xXIGetPropertyReply               32
 
+typedef struct {
+    uint16_t    deviceid;
+    uint16_t    pad;
+    Barrier     barrier;
+    uint32_t    eventid;
+} xXIBarrierReleasePointerInfo;
+
+typedef struct {
+    uint8_t     reqType;                /**< Input extension major opcode */
+    uint8_t     ReqType;                /**< Always X_XIBarrierReleasePointer */
+    uint16_t    length;
+    uint32_t    num_barriers;
+    /* array of xXIBarrierReleasePointerInfo */
+} xXIBarrierReleasePointerReq;
+#define sz_xXIBarrierReleasePointerReq       8
+
 /*************************************************************************************
  *                                                                                   *
  *                                      EVENTS                                       *
@@ -1035,10 +1053,39 @@ typedef struct
     uint32_t    pad3;
 } xXIPropertyEvent;
 
+typedef struct
+{
+    uint8_t     type;                   /**< Always GenericEvent */
+    uint8_t     extension;              /**< XI extension offset */
+    uint16_t    sequenceNumber;
+    uint32_t    length;                 /**< Length in 4 byte units */
+    uint16_t    evtype;                 /**< ::XI_BarrierHit or ::XI_BarrierLeave */
+    uint16_t    deviceid;
+    Time        time;
+    uint32_t    eventid;
+    Window      root;
+    Window      event;
+    Barrier     barrier;
+/* └──────── 32 byte boundary ────────┘ */
+    uint32_t    dtime;
+    uint32_t    flags;                  /**< ::XIBarrierPointerReleased
+                                             ::XIBarrierDeviceIsGrabbed */
+    uint16_t    sourceid;
+    int16_t     pad;
+    FP1616      root_x;
+    FP1616      root_y;
+    FP3232      dx;
+    FP3232      dy;
+} xXIBarrierEvent;
+
+typedef xXIBarrierEvent xXIBarrierHitEvent;
+typedef xXIBarrierEvent xXIBarrierPointerReleasedEvent;
+typedef xXIBarrierEvent xXIBarrierLeaveEvent;
 
 #undef Window
 #undef Time
 #undef Atom
 #undef Cursor
+#undef Barrier
 
 #endif /* _XI2PROTO_H_ */
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index c018026..402210f 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,93 @@ 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.
 
 :numbered!:
 [[xi22-usecases]]
-- 
1.7.11.7



More information about the xorg-devel mailing list