Add API to allow handling pointer lock requests and events

Similar to the fullscreen API there's now a pointer lock handler that
can be set to handle the requests to lock or unlock the pointer. A new
input type wpe_input_pointer_lock_event has been added, which extends
wpe_input_pointer_event to include the movement delta required by pointer
lock motion events.

Author: carlosgcampos

include/wpe/input.h

@@ -86,6 +86,11 @@ struct wpe_input_pointer_event {
     uint32_t modifiers;
 };
 
+struct wpe_input_pointer_lock_event {
+    struct wpe_input_pointer_event base;
+    double                         x_delta;
+    double                         y_delta;
+};
 
 enum wpe_input_axis_event_type {
     wpe_input_axis_event_type_null,

include/wpe/view-backend.h

@@ -53,6 +53,7 @@ struct wpe_view_backend;
 struct wpe_input_axis_event;
 struct wpe_input_keyboard_event;
 struct wpe_input_pointer_event;
+struct wpe_input_pointer_lock_event;
 struct wpe_input_touch_event;
 
 struct wpe_view_backend_client;
@@ -146,6 +147,37 @@ WPE_EXPORT
 void
 wpe_view_backend_set_fullscreen_handler(struct wpe_view_backend*, wpe_view_backend_fullscreen_handler handler, void* userdata);
 
+/**
+ * wpe_view_backend_pointer_lock_handler:
+ * @userdata: (transfer none): User data passed to the embedder.
+ * @enable: (transfer none): User data passed to the embedder.
+ *
+ * Type of functions used by an embedder to implement pointer lock in web views.
+ *
+ * Returns: a boolean indicating whether the operation was completed.
+ *
+ * Since: 1.14
+ */
+typedef bool (*wpe_view_backend_pointer_lock_handler)(void* userdata, bool enable);
+
+/**
+ * wpe_view_backend_set_pointer_lock_handler:
+ * @view_backend: (transfer none): The view backend to obtains events from.
+ * @handler: (transfer none): Function used by an embedder to implement pointer lock.
+ * @userdata: (transfer none): User data passed to the handler function.
+ *
+ * Handler function set by an embedder to implement pointer lock in web views.
+ *
+ * This function must be only used once for a given @view_backend, the handler
+ * cannot be changed once it has been set.
+ *
+ * Since: 1.14
+ */
+WPE_EXPORT
+void wpe_view_backend_set_pointer_lock_handler(struct wpe_view_backend*,
+                                               wpe_view_backend_pointer_lock_handler handler,
+                                               void*                                 userdata);
+
 WPE_EXPORT
 void
 wpe_view_backend_initialize(struct wpe_view_backend*);
@@ -231,12 +263,12 @@ struct wpe_view_backend_input_client {
     void (*handle_pointer_event)(void*, struct wpe_input_pointer_event*);
     void (*handle_axis_event)(void*, struct wpe_input_axis_event*);
     void (*handle_touch_event)(void*, struct wpe_input_touch_event*);
+    void (*handle_pointer_lock_event)(void*, struct wpe_input_pointer_lock_event*);
 
     /*< private >*/
     void (*_wpe_reserved0)(void);
     void (*_wpe_reserved1)(void);
     void (*_wpe_reserved2)(void);
-    void (*_wpe_reserved3)(void);
 };
 
 WPE_EXPORT
@@ -255,6 +287,9 @@ WPE_EXPORT
 void
 wpe_view_backend_dispatch_touch_event(struct wpe_view_backend*, struct wpe_input_touch_event*);
 
+WPE_EXPORT
+void wpe_view_backend_dispatch_pointer_lock_event(struct wpe_view_backend*, struct wpe_input_pointer_lock_event*);
+
 /**
  * wpe_view_backend_fullscreen_client:
  * @did_enter_fullscreen: Invoked after fullscreen has been successfully entered.
@@ -345,6 +380,31 @@ WPE_EXPORT
 void
 wpe_view_backend_dispatch_request_exit_fullscreen(struct wpe_view_backend*);
 
+/**
+ * wpe_view_backend_request_pointer_lock:
+ * @view_backend: (transfer none): The view backend that triggered the event.
+ *
+ * Request the platform to lock the pointer.
+ *
+ * Returns: a boolean indicating whether the operation was completed.
+ *
+ * Since: 1.14
+ */
+WPE_EXPORT
+bool wpe_view_backend_request_pointer_lock(struct wpe_view_backend*);
+
+/**
+ * wpe_view_backend_request_pointer_unlock:
+ * @view_backend: (transfer none): The view backend that triggered the event.
+ *
+ * Request the platform to unlock the pointer.
+ *
+ * Returns: a boolean indicating whether the operation was completed.
+ *
+ * Since: 1.14
+ */
+WPE_EXPORT
+bool wpe_view_backend_request_pointer_unlock(struct wpe_view_backend*);
 
 #ifdef __cplusplus
 }

src/view-backend-private.h

@@ -48,6 +48,9 @@ struct wpe_view_backend {
     wpe_view_backend_fullscreen_handler fullscreen_handler;
     void* fullscreen_handler_data;
 
+    wpe_view_backend_pointer_lock_handler pointer_lock_handler;
+    void*                                 pointer_lock_handler_data;
+
     uint32_t activity_state;
     uint32_t refresh_rate;
 };

src/view-backend.c

@@ -68,6 +68,9 @@ wpe_view_backend_destroy(struct wpe_view_backend* backend)
     backend->fullscreen_client = NULL;
     backend->fullscreen_client_data = NULL;
 
+    backend->pointer_lock_handler = NULL;
+    backend->pointer_lock_handler_data = NULL;
+
     backend->activity_state = 0;
     backend->refresh_rate = 0;
 
@@ -208,6 +211,14 @@ wpe_view_backend_dispatch_pointer_event(struct wpe_view_backend* backend, struct
         backend->input_client->handle_pointer_event(backend->input_client_data, event);
 }
 
+void
+wpe_view_backend_dispatch_pointer_lock_event(struct wpe_view_backend*             backend,
+                                             struct wpe_input_pointer_lock_event* event)
+{
+    if (backend->input_client)
+        backend->input_client->handle_pointer_lock_event(backend->input_client_data, event);
+}
+
 void
 wpe_view_backend_dispatch_axis_event(struct wpe_view_backend* backend, struct wpe_input_axis_event* event)
 {
@@ -266,3 +277,30 @@ wpe_view_backend_dispatch_request_exit_fullscreen(struct wpe_view_backend* backe
     if (backend->fullscreen_client)
         backend->fullscreen_client->request_exit_fullscreen(backend->fullscreen_client_data);
 }
+
+void
+wpe_view_backend_set_pointer_lock_handler(struct wpe_view_backend*              backend,
+                                          wpe_view_backend_pointer_lock_handler handler,
+                                          void*                                 userdata)
+{
+    assert(!backend->pointer_lock_handler);
+
+    backend->pointer_lock_handler = handler;
+    backend->pointer_lock_handler_data = userdata;
+}
+
+bool
+wpe_view_backend_request_pointer_lock(struct wpe_view_backend* backend)
+{
+    if (backend->pointer_lock_handler)
+        return backend->pointer_lock_handler(backend->pointer_lock_handler_data, true);
+    return false;
+}
+
+bool
+wpe_view_backend_request_pointer_unlock(struct wpe_view_backend* backend)
+{
+    if (backend->pointer_lock_handler)
+        return backend->pointer_lock_handler(backend->pointer_lock_handler_data, false);
+    return false;
+}