Rename keymap allocation API

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

1 files changed, 64 insertions, 15 deletions

diff --git a/include/xkbcommon/xkbcommon.h b/include/xkbcommon/xkbcommon.h
index fe72a74..18441c0 100644
--- a/include/xkbcommon/xkbcommon.h
+++ b/include/xkbcommon/xkbcommon.h
@@ -358,6 +358,7 @@ struct xkb_controls {
 
 /* Common keyboard description structure */
 struct xkb_desc {
+    unsigned int        refcnt;
     unsigned int        defined;
     unsigned short      flags;
     unsigned short      device_spec;
@@ -518,21 +519,6 @@ struct xkb_state {
 
 _XFUNCPROTOBEGIN
 
-_X_EXPORT extern struct xkb_desc *
-xkb_compile_keymap_from_rules(const struct xkb_rule_names *rules);
-
-_X_EXPORT extern struct xkb_desc *
-xkb_compile_keymap_from_components(const struct xkb_component_names * ktcsg);
-
-_X_EXPORT extern struct xkb_desc *
-xkb_compile_keymap_from_file(FILE *inputFile, const char *mapName);
-
-_X_EXPORT extern struct xkb_desc *
-xkb_compile_keymap_from_string(const char *string, const char *mapName);
-
-_X_EXPORT extern void
-xkb_free_keymap(struct xkb_desc *xkb);
-
 /*
  * Canonicalises component names by prepending the relevant component from
  * 'old' to the one in 'names' when the latter has a leading '+' or '|', and
@@ -570,6 +556,69 @@ xkb_key_get_syms(struct xkb_state *state, xkb_keycode_t key,
                  xkb_keysym_t **syms_out);
 
 /**
+ * @defgroup map Keymap management
+ * These utility functions allow you to create and deallocate XKB keymaps.
+ *
+ * @{
+ */
+
+/**
+ * The primary keymap entry point: creates a new XKB keymap from a set of
+ * RMLVO (Rules + Model + Layout + Variant + Option) names.
+ *
+ * You should almost certainly be using this and nothing else to create
+ * keymaps.
+ */
+_X_EXPORT extern struct xkb_desc *
+xkb_map_new_from_names(const struct xkb_rule_names *names);
+
+/**
+ * Deprecated entrypoint for legacy users who need to be able to compile
+ * XKB keymaps by KcCGST (Keycodes + Compat + Geometry + Symbols + Types)
+ * names.
+ *
+ * You should not use this unless you are the X server.  This entrypoint
+ * may well disappear in future releases.  Please, please, don't use it.
+ *
+ * Geometry will be ignored since xkbcommon does not support it in any way.
+ */
+_X_EXPORT extern struct xkb_desc *
+xkb_map_new_from_kccgst(const struct xkb_component_names *kccgst);
+
+enum xkb_keymap_format {
+    /** The current/classic XKB text format, as generated by xkbcomp -xkb. */
+    XKB_KEYMAP_FORMAT_TEXT_V1 = 1,
+};
+
+/**
+ * Creates an XKB keymap from a full text XKB keymap passed into the
+ * file descriptor.
+ */
+_X_EXPORT extern struct xkb_desc *
+xkb_map_new_from_fd(int fd, enum xkb_keymap_format format);
+
+/**
+ * Creates an XKB keymap from a full text XKB keymap serialised into one
+ * enormous string.
+ */
+_X_EXPORT extern struct xkb_desc *
+xkb_map_new_from_string(const char *string, enum xkb_keymap_format format);
+
+/**
+ * Takes a new reference on a keymap.
+ */
+_X_EXPORT extern void
+xkb_map_ref(struct xkb_desc *xkb);
+
+/**
+ * Releases a reference on a keymap.
+ */
+_X_EXPORT extern void
+xkb_map_unref(struct xkb_desc *xkb);
+
+/** @} */
+
+/**
  * @defgroup components XKB state components
  * Allows enumeration of state components such as modifiers and groups within
  * the current keymap.