Add state serialisation API

Signed-off-by: Daniel Stone <daniel@fooishbar.org>

include/xkbcommon/xkbcommon.h

@@ -63,6 +63,7 @@ THE USE OR PERFORMANCE OF THIS SOFTWARE.
 typedef uint32_t xkb_keycode_t;
 typedef uint32_t xkb_keysym_t;
 typedef uint32_t xkb_mod_index_t;
+typedef uint32_t xkb_mod_mask_t;
 typedef uint32_t xkb_group_index_t;
 typedef uint32_t xkb_led_index_t;
 
@@ -741,6 +742,52 @@ enum xkb_state_component {
         /**< Combinatination of depressed, latched, and locked. */
 };
 
+/**
+ * Updates a state object from a set of explicit masks.  This entrypoint is
+ * really only for window systems and the like, where a master process
+ * holds an xkb_state, then serialises it over a wire protocol, and clients
+ * then use the serialisation to feed in to their own xkb_state.
+ *
+ * All parameters must always be passed, or the resulting state may be
+ * incoherent.
+ *
+ * The serialisation is lossy and will not survive round trips; it must only
+ * be used to feed slave state objects, and must not be used to update the
+ * master state.
+ *
+ * Please do not use this unless you fit the description above.
+ */
+_X_EXPORT void
+xkb_state_update_mask(struct xkb_state *state,
+                      xkb_mod_mask_t base_mods,
+                      xkb_mod_mask_t latched_mods,
+                      xkb_mod_mask_t locked_mods,
+                      xkb_group_index_t base_group,
+                      xkb_group_index_t latched_group,
+                      xkb_group_index_t locked_group);
+
+/**
+ * The counterpart to xkb_state_update_mask, to be used on the server side
+ * of serialisation.  Returns a xkb_mod_mask_t representing the given
+ * component(s) of the state.
+ *
+ * This function should not be used in regular clients; please use the
+ * xkb_state_mod_*_is_active or xkb_state_foreach_active_mod API instead.
+ *
+ * Can return NULL on failure.
+ */
+_X_EXPORT xkb_mod_mask_t
+xkb_state_serialise_mods(struct xkb_state *state,
+                         enum xkb_state_component component);
+
+/**
+ * The group equivalent of xkb_state_serialise_mods: please see its
+ * documentation.
+ */
+_X_EXPORT xkb_group_index_t
+xkb_state_serialise_group(struct xkb_state *state,
+                          enum xkb_state_component component);
+
 /**
  * Returns 1 if the modifier specified by 'name' is active in the manner
  * specified by 'type', 0 if it is unset, or -1 if the modifier does not

src/state.c

@@ -499,14 +499,12 @@ xkb_state_led_update_all(struct xkb_state *state)
 }
 
 /**
- * Given a particular key event, updates the state structure to reflect the
- * new modifiers.
+ * Calculates the derived state (effective mods/group and LEDs) from an
+ * up-to-date xkb_state.
  */
-void
-xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key, int down)
+static void
+xkb_state_update_derived(struct xkb_state *state)
 {
-    xkb_filter_apply_all(state, key, down);
-
     state->mods = (state->base_mods | state->latched_mods | state->locked_mods);
     /* FIXME: Clamp/wrap locked_group */
     state->group = state->locked_group + state->base_group +
@@ -516,6 +514,101 @@ xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key, int down)
     xkb_state_led_update_all(state);
 }
 
+/**
+ * Given a particular key event, updates the state structure to reflect the
+ * new modifiers.
+ */
+void
+xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key, int down)
+{
+    xkb_filter_apply_all(state, key, down);
+    xkb_state_update_derived(state);
+}
+
+/**
+ * Updates the state from a set of explicit masks as gained from
+ * xkb_state_serialise_mods and xkb_state_serialise_groups.  As noted in the
+ * documentation for these functions in xkbcommon.h, this round-trip is
+ * lossy, and should only be used to update a slave state mirroring the
+ * master, e.g. in a client/server window system.
+ */
+void
+xkb_state_update_mask(struct xkb_state *state,
+                      xkb_mod_mask_t base_mods,
+                      xkb_mod_mask_t latched_mods,
+                      xkb_mod_mask_t locked_mods,
+                      xkb_group_index_t base_group,
+                      xkb_group_index_t latched_group,
+                      xkb_group_index_t locked_group)
+{
+    xkb_mod_mask_t mod;
+
+    state->base_mods = 0;
+    state->latched_mods = 0;
+    state->locked_mods = 0;
+    for (mod = 0; mod < xkb_map_num_mods(state->xkb); mod++) {
+        xkb_mod_mask_t idx = (1 << mod);
+        if (base_mods & idx)
+            state->base_mods |= idx;
+        if (latched_mods & idx)
+            state->latched_mods |= idx;
+        if (locked_mods & idx)
+            state->locked_mods |= idx;
+    }
+
+    state->base_group = base_group;
+    state->latched_group = latched_group;
+    state->locked_group = locked_group;
+
+    xkb_state_update_derived(state);
+}
+
+/**
+ * Serialises the requested modifier state into an xkb_mod_mask_t, with all
+ * the same disclaimers as in xkb_state_update_mask.
+ */
+xkb_mod_mask_t
+xkb_state_serialise_mods(struct xkb_state *state,
+                         enum xkb_state_component type)
+{
+    xkb_mod_mask_t ret = 0;
+
+    if (type == XKB_STATE_EFFECTIVE)
+        return state->mods;
+
+    if (type & XKB_STATE_DEPRESSED)
+        ret |= state->base_mods;
+    if (type & XKB_STATE_LATCHED)
+        ret |= state->latched_mods;
+    if (type & XKB_STATE_LOCKED)
+        ret |= state->locked_mods;
+
+    return ret;
+}
+
+/**
+ * Serialises the requested group state, with all the same disclaimers as
+ * in xkb_state_update_mask.
+ */
+xkb_group_index_t
+xkb_state_serialise_group(struct xkb_state *state,
+                          enum xkb_state_component type)
+{
+    xkb_group_index_t ret = 0;
+
+    if (type == XKB_STATE_EFFECTIVE)
+        return state->group;
+
+    if (type & XKB_STATE_DEPRESSED)
+        ret += state->base_group;
+    if (type & XKB_STATE_LATCHED)
+        ret += state->latched_group;
+    if (type & XKB_STATE_LOCKED)
+        ret += state->locked_group;
+
+    return ret;
+}
+
 /**
  * Returns 1 if the given modifier is active with the specified type(s), 0 if
  * not, or -1 if the modifier is invalid.

test/state.c

@@ -89,29 +89,14 @@ print_state(struct xkb_state *state)
     }
 }
 
-int
-main(int argc, char *argv[])
+static void
+test_update_key(struct xkb_desc *xkb)
 {
-    struct xkb_rule_names rmlvo;
-    struct xkb_desc *xkb;
-    struct xkb_state *state;
-    int num_syms;
+    struct xkb_state *state = xkb_state_new(xkb);
     xkb_keysym_t *syms;
+    int num_syms;
 
-    rmlvo.rules = "evdev";
-    rmlvo.model = "pc104";
-    rmlvo.layout = "us";
-    rmlvo.variant = NULL;
-    rmlvo.options = NULL;
-
-    xkb = xkb_map_new_from_names(&rmlvo);
-
-    if (!xkb) {
-        fprintf(stderr, "Failed to compile keymap\n");
-        exit(1);
-    }
-
-    state = xkb_state_new(xkb);
+    assert(state);
 
     /* LCtrl down */
     xkb_state_update_key(state, KEY_LEFTCTRL + EVDEV_OFFSET, 1);
@@ -164,7 +149,78 @@ main(int argc, char *argv[])
     assert(num_syms == 1 && syms[0] == XK_q);
 
     xkb_state_unref(state);
-    xkb_map_unref(xkb);
-
-    return 0;
+}
+
+static void
+test_serialisation(struct xkb_desc *xkb)
+{
+    struct xkb_state *state = xkb_state_new(xkb);
+    xkb_mod_mask_t base_mods;
+    xkb_mod_mask_t latched_mods;
+    xkb_mod_mask_t locked_mods;
+    xkb_mod_mask_t effective_mods;
+    xkb_mod_index_t caps, shift, ctrl;
+    xkb_group_index_t base_group = 0;
+    xkb_group_index_t latched_group = 0;
+    xkb_group_index_t locked_group = 0;
+
+    assert(state);
+
+    caps = xkb_map_mod_get_index(state->xkb, "Caps Lock");
+    assert(caps != XKB_MOD_INVALID);
+    shift = xkb_map_mod_get_index(state->xkb, "Shift");
+    assert(shift != XKB_MOD_INVALID);
+    ctrl = xkb_map_mod_get_index(state->xkb, "Control");
+    assert(ctrl != XKB_MOD_INVALID);
+
+    xkb_state_update_key(state, KEY_CAPSLOCK + EVDEV_OFFSET, 1);
+    xkb_state_update_key(state, KEY_CAPSLOCK + EVDEV_OFFSET, 0);
+    base_mods = xkb_state_serialise_mods(state, XKB_STATE_DEPRESSED);
+    assert(base_mods == 0);
+    latched_mods = xkb_state_serialise_mods(state, XKB_STATE_LATCHED);
+    assert(latched_mods == 0);
+    locked_mods = xkb_state_serialise_mods(state, XKB_STATE_LOCKED);
+    assert(locked_mods == (1 << caps));
+    effective_mods = xkb_state_serialise_mods(state, XKB_STATE_EFFECTIVE);
+    assert(effective_mods == locked_mods);
+
+    xkb_state_update_key(state, KEY_LEFTSHIFT + EVDEV_OFFSET, 1);
+    base_mods = xkb_state_serialise_mods(state, XKB_STATE_DEPRESSED);
+    assert(base_mods == (1 << shift));
+    latched_mods = xkb_state_serialise_mods(state, XKB_STATE_LATCHED);
+    assert(latched_mods == 0);
+    locked_mods = xkb_state_serialise_mods(state, XKB_STATE_LOCKED);
+    assert(locked_mods == (1 << caps));
+    effective_mods = xkb_state_serialise_mods(state, XKB_STATE_EFFECTIVE);
+    assert(effective_mods == (base_mods | locked_mods));
+
+    base_mods |= (1 << ctrl);
+    xkb_state_update_mask(state, base_mods, latched_mods, locked_mods,
+                          base_group, latched_group, locked_group);
+
+    assert(xkb_state_mod_index_is_active(state, ctrl, XKB_STATE_DEPRESSED));
+    assert(xkb_state_mod_index_is_active(state, ctrl, XKB_STATE_EFFECTIVE));
+
+    xkb_state_unref(state);
+}
+
+int
+main(int argc, char *argv[])
+{
+    struct xkb_rule_names rmlvo;
+    struct xkb_desc *xkb;
+
+    rmlvo.rules = "evdev";
+    rmlvo.model = "pc104";
+    rmlvo.layout = "us";
+    rmlvo.variant = NULL;
+    rmlvo.options = NULL;
+
+    xkb = xkb_map_new_from_names(&rmlvo);
+    assert(xkb);
+
+    test_update_key(xkb);
+    test_serialisation(xkb);
+
+    xkb_map_unref(xkb);
 }