[pango/simple-fontmap: 1/13] Add PangoHbFontmap

[Matthias Clasen <matthiasc src gnome org>]

commit e420b791964b26e7bcd008184688fc20ffc7be2f
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Oct 29 19:08:02 2021 -0400

    Add PangoHbFontmap
    
    This is a fontmap implementation for use with PangoHbFont,
    which lets you add individual faces. It handles caching
    and lookups and is designed to let subclasses simply provide
    a populate vfunc.
    
    Note that the load_fontset implementation here is similar in
    style to the one we have in PangoFontMap: for each family
    in the font description, pick the best matching face.

 pango/meson.build               |   2 +
 pango/pango-hbfont.c            |   3 +-
 pango/pango-hbfontmap-private.h |  58 ++++
 pango/pango-hbfontmap.c         | 709 ++++++++++++++++++++++++++++++++++++++++
 pango/pango-hbfontmap.h         |  51 +++
 pango/pango.h                   |   1 +
 6 files changed, 823 insertions(+), 1 deletion(-)
---
diff --git a/pango/meson.build b/pango/meson.build
index 08c3cd50..8251bada 100644
--- a/pango/meson.build
+++ b/pango/meson.build
@@ -37,6 +37,7 @@ pango_sources = [
   'pango-hbface.c',
   'pango-hbfamily.c',
   'pango-hbfont.c',
+  'pango-hbfontmap.c',
 ]
 
 pango_headers = [
@@ -69,6 +70,7 @@ pango_headers = [
   'pango-utils.h',
   'pango-hbface.h',
   'pango-hbfont.h',
+  'pango-hbfontmap.h',
 ]
 
 pango_installed_headers = pango_headers + [ 'pango-version-macros.h' ]
diff --git a/pango/pango-hbfont.c b/pango/pango-hbfont.c
index ed57a6bc..d30b9cdb 100644
--- a/pango/pango-hbfont.c
+++ b/pango/pango-hbfont.c
@@ -803,7 +803,8 @@ pango_hb_font_new (PangoHbFace       *face,
   self->features = g_memdup2 (features, sizeof (hb_feature_t) * n_features);
   self->n_features = n_features;
   self->variations = g_strdup (variations);
-  self->gravity = gravity;
+  if (gravity != PANGO_GRAVITY_AUTO)
+    self->gravity = gravity;
   if (matrix)
     self->matrix = *matrix;
 
diff --git a/pango/pango-hbfontmap-private.h b/pango/pango-hbfontmap-private.h
new file mode 100644
index 00000000..be52b645
--- /dev/null
+++ b/pango/pango-hbfontmap-private.h
@@ -0,0 +1,58 @@
+/* Pango
+ *
+ * Copyright (C) 2021 Red Hat Software
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.         See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#pragma once
+
+#include <pango/pango-hbfontmap.h>
+
+G_BEGIN_DECLS
+
+struct _PangoHbFontMap
+{
+  PangoFontMap parent_instance;
+
+  GPtrArray *added_faces;
+  GHashTable *families_hash;
+  GPtrArray *families;
+  GHashTable *fontsets;
+  GQueue fontset_cache;
+
+  double dpi;
+  gboolean in_populate;
+};
+
+/**
+ * PangoHbFontMapClass:
+ * @populate: Subclasses should call pango_hb_font_map_add_face to populate
+ *   the map with faces and families in this vfunc.
+ */
+struct _PangoHbFontMapClass
+{
+  PangoFontMapClass parent_class;
+
+  void (* populate) (PangoHbFontMap *self);
+
+  gpointer reserved[10];
+};
+
+PANGO_AVAILABLE_IN_1_52
+void                    pango_hb_font_map_repopulate    (PangoHbFontMap *self);
+
+G_END_DECLS
diff --git a/pango/pango-hbfontmap.c b/pango/pango-hbfontmap.c
new file mode 100644
index 00000000..9fede586
--- /dev/null
+++ b/pango/pango-hbfontmap.c
@@ -0,0 +1,709 @@
+/* Pango
+ *
+ * Copyright (C) 2021 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.         See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include "config.h"
+#include <math.h>
+
+#include <gio/gio.h>
+
+#include "pango-hbfontmap-private.h"
+#include "pango-hbfamily-private.h"
+#include "pango-hbface-private.h"
+#include "pango-hbfont-private.h"
+#include "pango-context.h"
+#include "pango-impl-utils.h"
+#include "pango-fontset-simple-private.h"
+#include "pango-trace-private.h"
+
+#include <hb-ot.h>
+
+
+/**
+ * PangoHbFontMap:
+ *
+ * `PangoHbFontMap` is a `PangoFontMap` subclass for use with
+ * `PangoHbFace` and `PangoHbFont`. It handles caching and
+ * lookup of faces and fonts.
+ *
+ * Subclasses populate the fontmap using backend-specific APIs
+ * to enumerate the available fonts on the sytem, but it is
+ * also possible to create an instance of `PangoHbFontMap` and
+ * populate it manually using [method@Pango.HbFontMap.add_file]
+ * and [method@Pango.HbFontMap.add_face].
+ */
+
+
+/* The central api is load_fontset, which takes a font description
+ * and language, finds the matching faces, and creates a PangoFontSet
+ * for them. To speed this operation up, the font map maintains a
+ * cache of fontsets (in the form of a GQueue) and has a hash table
+ * for looking up existing fontsets. The PangoFontsetCached object
+ * is the fontset subclass that is used here, and it contains the
+ * necessary data for the cashing and hashing.
+ */
+
+/* The number of fontsets we keep in the fontset cache */
+
+#define FONTSET_CACHE_SIZE 256
+
+
+/* {{{ GListModel implementation */
+
+static GType
+pango_hb_font_map_get_item_type (GListModel *list)
+{
+  return PANGO_TYPE_FONT_FAMILY;
+}
+
+static guint
+pango_hb_font_map_get_n_items (GListModel *list)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (list);
+
+  return self->families->len;
+}
+
+static gpointer
+pango_hb_font_map_get_item (GListModel *list,
+                            guint       position)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (list);
+
+  if (position < self->families->len)
+    return g_object_ref (g_ptr_array_index (self->families, position));
+
+  return NULL;
+}
+
+static void
+pango_hb_font_map_list_model_init (GListModelInterface *iface)
+{
+  iface->get_item_type = pango_hb_font_map_get_item_type;
+  iface->get_n_items = pango_hb_font_map_get_n_items;
+  iface->get_item = pango_hb_font_map_get_item;
+}
+
+/* }}} */
+/* {{{ Fontset caching and hashing */
+
+typedef struct _PangoFontsetCached PangoFontsetCached;
+
+struct _PangoFontsetCached
+{
+  PangoFontsetSimple simple;
+  PangoFontDescription *description;
+  GList cache_link;
+};
+
+typedef PangoFontsetSimpleClass PangoFontsetCachedClass;
+
+GType pango_fontset_cached_get_type (void) G_GNUC_CONST;
+
+G_DEFINE_TYPE (PangoFontsetCached, pango_fontset_cached, PANGO_TYPE_FONTSET_SIMPLE);
+
+static void
+pango_fontset_cached_init (PangoFontsetCached *fontset)
+{
+}
+
+static void
+pango_fontset_cached_finalize (GObject *object)
+{
+  PangoFontsetCached *fontset = (PangoFontsetCached *)object;
+
+  pango_font_description_free (fontset->description);
+
+  G_OBJECT_CLASS (pango_fontset_cached_parent_class)->finalize (object);
+}
+
+static void
+pango_fontset_cached_class_init (PangoFontsetCachedClass *class)
+{
+  GObjectClass *object_class = G_OBJECT_CLASS (class);
+
+  object_class->finalize = pango_fontset_cached_finalize;
+}
+
+static PangoFontsetSimple *
+pango_fontset_cached_new (const PangoFontDescription *description,
+                          PangoLanguage              *language)
+{
+  PangoFontsetCached *self;
+
+  self = g_object_new (pango_fontset_cached_get_type (), NULL);
+  ((PangoFontsetSimple *)self)->language = language;
+  self->description = pango_font_description_copy (description);
+
+  return PANGO_FONTSET_SIMPLE (self);
+}
+
+#define FNV1_32_INIT ((guint32)0x811c9dc5)
+
+static guint
+pango_fontset_cached_hash (const PangoFontsetCached *fontset)
+{
+  guint32 hash = FNV1_32_INIT;
+
+  return (hash ^
+          GPOINTER_TO_UINT (((PangoFontsetSimple *)fontset)->language) ^
+          pango_font_description_hash (fontset->description));
+}
+
+static gboolean
+pango_fontset_cached_equal (const PangoFontsetCached *a,
+                            const PangoFontsetCached *b)
+{
+  return ((PangoFontsetSimple *)a)->language == ((PangoFontsetSimple *)b)->language &&
+         pango_font_description_equal (a->description, b->description);
+}
+
+static void
+pango_fontset_cache (PangoFontsetCached *fontset,
+                     PangoHbFontMap *self)
+{
+  GQueue *cache = &self->fontset_cache;
+  GList *link = &fontset->cache_link;
+
+  if (link->data == fontset)
+    {
+      /* Already in cache, move to head */
+      if (link == cache->head)
+        return;
+
+      g_queue_unlink (cache, link);
+    }
+  else
+    {
+      /* Not in cache yet. Make room... */
+      if (cache->length == FONTSET_CACHE_SIZE)
+        {
+          GList *old = g_queue_pop_tail_link (cache);
+          g_hash_table_remove (self->fontsets, old->data);
+          old->data = NULL;
+        }
+    }
+
+  link->data = fontset;
+  link->prev = NULL;
+  link->next = NULL;
+  g_queue_push_head_link (cache, link);
+}
+
+/* }}} */
+/* {{{ Utilities */
+
+#define DONTCARE 2
+
+static guint
+pango_hb_family_hash (const PangoHbFamily *self)
+{
+  const signed char *p;
+  guint32 h = 5381;
+
+  for (p = (const signed char *)self->name; *p != '\0'; p++)
+    h = (h << 5) + h + g_ascii_tolower (*p);
+
+  return h;
+}
+
+static gboolean
+pango_hb_family_equal (const PangoHbFamily *a,
+                       const PangoHbFamily *b)
+{
+  if (g_ascii_strcasecmp (a->name, b->name) != 0)
+    return FALSE;
+
+  return a->variable == DONTCARE ||
+         b->variable == DONTCARE ||
+         a->variable == b->variable;
+}
+
+static PangoHbFamily *
+find_family (PangoHbFontMap *self,
+             const char     *family_name,
+             gboolean        variable)
+{
+  PangoHbFamily lookup;
+
+  lookup.name = (char *)family_name;
+  lookup.variable = variable;
+
+  return PANGO_HB_FAMILY (g_hash_table_lookup (self->families_hash, &lookup));
+}
+
+static void
+clear_caches (PangoHbFontMap *self)
+{
+  g_hash_table_remove_all (self->fontsets);
+  g_queue_init (&self->fontset_cache);
+}
+
+static void
+font_description_get_features (const PangoFontDescription *description,
+                               hb_feature_t               *features,
+                               unsigned int                length,
+                               unsigned int               *n_features)
+{
+
+#define ADD_FEATURE(name) \
+ features[*n_features].tag = HB_TAG (name[0], name[1], name[2], name[3]); \
+ features[*n_features].value = 1; \
+ features[*n_features].start = 0; \
+ features[*n_features].end = (unsigned int) -1; \
+ (*n_features)++
+
+  g_assert (length >= 2);
+
+  *n_features = 0;
+  switch (pango_font_description_get_variant (description))
+    {
+    case PANGO_VARIANT_SMALL_CAPS:
+      ADD_FEATURE ("smcp");
+      break;
+    case PANGO_VARIANT_ALL_SMALL_CAPS:
+      ADD_FEATURE ("smcp");
+      ADD_FEATURE ("c2sc");
+      break;
+    case PANGO_VARIANT_PETITE_CAPS:
+      ADD_FEATURE ("pcap");
+      break;
+    case PANGO_VARIANT_ALL_PETITE_CAPS:
+      ADD_FEATURE ("pcap");
+      ADD_FEATURE ("c2pc");
+      break;
+    case PANGO_VARIANT_UNICASE:
+      ADD_FEATURE ("unic");
+      break;
+    case PANGO_VARIANT_TITLE_CAPS:
+      ADD_FEATURE ("titl");
+      break;
+    case PANGO_VARIANT_NORMAL:
+      break;
+    default:
+      g_assert_not_reached ();
+    }
+
+#undef ADD_FEATURE
+}
+
+ /* }}} */
+/* {{{ PangoFontMap implementation */
+
+G_DEFINE_TYPE_WITH_CODE (PangoHbFontMap, pango_hb_font_map, PANGO_TYPE_FONT_MAP,
+                         G_IMPLEMENT_INTERFACE (G_TYPE_LIST_MODEL, pango_hb_font_map_list_model_init))
+
+
+static void
+pango_hb_font_map_init (PangoHbFontMap *self)
+{
+  self->added_faces = g_ptr_array_new_with_free_func (g_object_unref);
+  self->families = g_ptr_array_new_with_free_func (g_object_unref);
+  self->families_hash = g_hash_table_new_full ((GHashFunc) pango_hb_family_hash,
+                                               (GEqualFunc) pango_hb_family_equal,
+                                               NULL,
+                                               NULL);
+  self->fontsets = g_hash_table_new_full ((GHashFunc) pango_fontset_cached_hash,
+                                          (GEqualFunc) pango_fontset_cached_equal,
+                                          NULL,
+                                          (GDestroyNotify) g_object_unref);
+  g_queue_init (&self->fontset_cache);
+  self->dpi = 96.;
+}
+
+static void
+pango_hb_font_map_finalize (GObject *object)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (object);
+
+  g_ptr_array_unref (self->added_faces);
+  g_ptr_array_unref (self->families);
+  g_hash_table_unref (self->fontsets);
+
+  G_OBJECT_CLASS (pango_hb_font_map_parent_class)->finalize (object);
+}
+
+/* Load a font from the first matching family */
+static PangoFont *
+pango_hb_font_map_load_font (PangoFontMap               *map,
+                             PangoContext               *context,
+                             const PangoFontDescription *description)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (map);
+  PangoFontsetSimple *fontset;
+  PangoLanguage *language;
+  PangoFont *font = NULL;
+
+  if (self->families->len == 0)
+    return NULL;
+
+  if (context)
+    language = pango_context_get_language (context);
+  else
+    language = NULL;
+
+  fontset = PANGO_FONTSET_SIMPLE (pango_font_map_load_fontset (map, context, description, language));
+  if (fontset->fonts->len > 0)
+    font = g_object_ref (PANGO_FONT (g_ptr_array_index (fontset->fonts, 0)));
+  g_object_unref (fontset);
+
+  return font;
+}
+
+/* Add one font for each family we find */
+static PangoFontset *
+pango_hb_font_map_load_fontset (PangoFontMap               *map,
+                                PangoContext               *context,
+                                const PangoFontDescription *description,
+                                PangoLanguage              *language)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (map);
+  PangoFontsetCached lookup;
+  PangoFontsetSimple *fontset;
+  int size;
+  const char *variations;
+  hb_feature_t features[10];
+  unsigned int n_features;
+  PangoGravity gravity;
+  const PangoMatrix *matrix;
+  const char *family_name;
+  char **families;
+  PangoFontDescription *copy;
+  PangoHbFamily *family;
+  PangoHbFace *face;
+  PangoHbFont *font;
+  gint64 before G_GNUC_UNUSED;
+
+  before = PANGO_TRACE_CURRENT_TIME;
+
+  if (!language)
+    language = pango_context_get_language (context);
+
+  family_name = pango_font_description_get_family (description);
+
+  ((PangoFontsetSimple *) &lookup)->language = language;
+  lookup.description = (PangoFontDescription *)description;
+  fontset = g_hash_table_lookup (self->fontsets, &lookup);
+
+  if (fontset)
+    goto done;
+
+  fontset = pango_fontset_cached_new (description, language);
+
+  if (self->families->len == 0)
+    {
+      g_warning ("Font map contains no fonts!!!!");
+      goto done_no_cache;
+    }
+
+  if (pango_font_description_get_size_is_absolute (description))
+    size = pango_font_description_get_size (description) * 72. / self->dpi;
+  else
+    size = pango_font_description_get_size (description);
+
+  variations = pango_font_description_get_variations (description);
+  font_description_get_features (description, features, G_N_ELEMENTS (features), &n_features);
+  if ((pango_font_description_get_set_fields (description) & PANGO_FONT_MASK_GRAVITY) != 0 &&
+      pango_font_description_get_gravity (description) != PANGO_GRAVITY_SOUTH)
+    gravity = pango_font_description_get_gravity (description);
+  else
+    gravity = PANGO_GRAVITY_AUTO;
+  matrix = pango_context_get_matrix (context);
+
+  families = g_strsplit (family_name ? family_name : "", ",", -1);
+
+  /* Unset gravity and variant since PangoHbFace does not have these fields */
+  copy = pango_font_description_copy_static (description);
+  pango_font_description_unset_fields (copy, PANGO_FONT_MASK_VARIATIONS |
+                                             PANGO_FONT_MASK_GRAVITY |
+                                             PANGO_FONT_MASK_VARIANT);
+
+  for (int i = 0; families[i]; i++)
+    {
+      family = find_family (self, families[i], variations ? TRUE : DONTCARE);
+      if (!family && variations)
+        family = find_family (self, families[i], DONTCARE);
+      if (!family)
+        continue;
+
+      face = pango_hb_family_find_face (family, copy, language);
+      if (!face)
+        continue;
+
+      font = pango_hb_font_new (face, size, features, n_features, variations, gravity, self->dpi, matrix);
+      pango_fontset_simple_append (fontset, PANGO_FONT (font));
+    }
+
+  g_strfreev (families);
+
+  /* Returning an empty fontset lets to bad outcomes.
+   * We look for "sans-serif", and if that fails, just use
+   * the first face we find as ultimate fallback.
+   */
+  if (pango_fontset_simple_size (fontset) == 0)
+    {
+      pango_font_description_set_family_static (copy, "sans-serif");
+
+      family = find_family (self, "sans-serif", DONTCARE);
+      if (!family)
+        family = g_ptr_array_index (self->families, 0);
+
+      face = pango_hb_family_find_face (family, copy, language);
+      if (!face)
+        {
+          pango_font_description_unset_fields (copy, PANGO_FONT_MASK_STYLE |
+                                                     PANGO_FONT_MASK_WEIGHT |
+                                                     PANGO_FONT_MASK_STRETCH);
+
+          face = pango_hb_family_find_face (family, copy, language);
+        }
+      if (!face)
+        face = pango_hb_family_find_face (family, copy, NULL);
+
+      if (face)
+        {
+          font = pango_hb_font_new (face, size, features, n_features, variations, gravity, self->dpi, 
matrix);
+          pango_fontset_simple_append (fontset, PANGO_FONT (font));
+        }
+    }
+
+  pango_font_description_free (copy);
+
+  g_hash_table_add (self->fontsets, fontset);
+
+done:
+  pango_fontset_cache ((PangoFontsetCached *)fontset, self);
+
+  if (pango_fontset_simple_size (fontset) == 0)
+    {
+      char *s = pango_font_description_to_string (description);
+      g_warning ("All font fallbacks failed for \"%s\", in %s !!!!", s, pango_language_to_string (language));
+      g_free (s);
+    }
+
+done_no_cache:
+  pango_trace_mark (before, "pango_hb_fontmap_load_fontset", "%s", family_name);
+
+  return g_object_ref (PANGO_FONTSET (fontset));
+}
+
+static void
+pango_hb_font_map_list_families (PangoFontMap      *map,
+                                     PangoFontFamily ***families,
+                                     int               *n_families)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (map);
+
+  if (n_families)
+    *n_families = self->families->len;
+
+  if (families)
+    *families = g_memdup2 (self->families->pdata, self->families->len * sizeof (PangoFontFamily *));
+}
+
+static PangoFontFamily *
+pango_hb_font_map_get_family (PangoFontMap *map,
+                                  const char   *name)
+{
+  PangoHbFontMap *self = PANGO_HB_FONT_MAP (map);
+
+  return PANGO_FONT_FAMILY (find_family (self, name, DONTCARE));
+}
+
+static void
+pango_hb_font_map_populate (PangoHbFontMap *self)
+{
+}
+
+static void
+pango_hb_font_map_class_init (PangoHbFontMapClass *class)
+{
+  GObjectClass *object_class = G_OBJECT_CLASS (class);
+  PangoFontMapClass *fontmap_class = PANGO_FONT_MAP_CLASS (class);
+
+  object_class->finalize = pango_hb_font_map_finalize;
+
+  fontmap_class->load_font = pango_hb_font_map_load_font;
+  fontmap_class->load_fontset = pango_hb_font_map_load_fontset;
+  fontmap_class->list_families = pango_hb_font_map_list_families;
+  fontmap_class->get_family = pango_hb_font_map_get_family;
+
+  class->populate = pango_hb_font_map_populate;
+}
+
+/* }}} */
+/* {{{ Private API */
+
+/*< private >
+ * pango_hb_font_map_repopulate:
+ * @self: a `PangoHbFontMap`
+ *
+ * Clear all cached information and repopulate the fontmap with
+ * families and faces.
+ *
+ * Subclasses should call this when their configuration changes
+ * in a way that requires recreating families and faces.
+ */
+void
+pango_hb_font_map_repopulate (PangoHbFontMap *self)
+{
+  int removed, added;
+
+  clear_caches (self);
+
+  removed = self->families->len;
+
+  g_hash_table_remove_all (self->families_hash);
+  g_ptr_array_set_size (self->families, 0);
+
+  self->in_populate = TRUE;
+
+  PANGO_HB_FONT_MAP_GET_CLASS (self)->populate (self);
+
+  for (int i = 0; i < self->added_faces->len; i++)
+    {
+      PangoHbFace *face = PANGO_HB_FACE (g_ptr_array_index (self->added_faces, i));
+
+      pango_hb_font_map_add_face (self, face);
+    }
+
+  self->in_populate = FALSE;
+
+  added = self->families->len;
+
+  g_list_model_items_changed (G_LIST_MODEL (self), 0, removed, added);
+
+  pango_font_map_changed (PANGO_FONT_MAP (self));
+}
+
+
+/* }}} */
+/* {{{ Public API */
+
+/**
+ * pango_hb_font_map_new:
+ *
+ * Creates a new `PangoHbFontmMap`.
+ *
+ * Returns: A newly created `PangoHbFontMap
+ *
+ * Since: 1.52
+ */
+PangoHbFontMap *
+pango_hb_font_map_new (void)
+{
+  return g_object_new (PANGO_TYPE_HB_FONT_MAP, NULL);
+}
+
+/**
+ * pango_hb_font_map_add_face:
+ * @self: a `PangoHbFontMap`
+ * @face: a `PangoHbFace`
+ *
+ * Adds @face to the `PangoHbFontMap`.
+ *
+ * This is most useful for creating transformed
+ * faces or aliases. See [method@Pango.HbFace.new_variant].
+ *
+ * Since: 1.52
+ */
+void
+pango_hb_font_map_add_face (PangoHbFontMap *self,
+                            PangoHbFace    *face)
+{
+  PangoFontMap *map = PANGO_FONT_MAP (self);
+  const char *family_name;
+  PangoHbFamily *family;
+
+  if (pango_font_description_get_set_fields (face->description) &
+      (PANGO_FONT_MASK_VARIANT | PANGO_FONT_MASK_GRAVITY | PANGO_FONT_MASK_VARIATIONS))
+    g_warning ("Font description for PangoHbFace includes things that it shouldn't");
+
+  if (!self->in_populate)
+    g_ptr_array_add (self->added_faces, g_object_ref (face));
+
+  family_name = pango_font_description_get_family (face->description);
+  family = PANGO_HB_FAMILY (pango_font_map_get_family (map, family_name));
+  if (!family)
+    {
+      int position;
+
+      position = self->families->len;
+
+      family = pango_hb_family_new (map,
+                                    family_name,
+                                    pango_hb_face_is_monospace (face),
+                                    pango_hb_face_is_variable (face));
+      g_ptr_array_add (self->families, family);
+      g_hash_table_add (self->families_hash, family);
+
+      if (!self->in_populate)
+        g_list_model_items_changed (G_LIST_MODEL (self), position, 0, 1);
+    }
+
+  pango_hb_family_add_face (family, face);
+
+  clear_caches (self);
+}
+
+/**
+ * pango_hb_font_map_add_file:
+ * @self: a `PangoHbFontMap`
+ * @file: font filename
+ *
+ * Creates a new `PangoHbFace` and adds it.
+ *
+ * Since: 1.52
+ */
+void
+pango_hb_font_map_add_file (PangoHbFontMap *self,
+                            const char     *file)
+{
+  PangoHbFace *face;
+
+  face = pango_hb_face_new_from_file (file, 0, -1, NULL, NULL);
+  pango_hb_font_map_add_face (self, face);
+  g_object_unref (face);
+}
+
+/**
+ * pango_hb_font_map_set_resolution:
+ * @self: a `PangoHbFontMap`
+ * @dpi: the new resolution, in "dots per inch"
+ *
+ * Sets the resolution for the fontmap.
+ *
+ * This is a scale factor between points specified in a
+ * `PangoFontDescription` and Cairo units. The default value
+ * is 96, meaning that a 10 point font will be 13 units high.
+ * (10 * 96. / 72. = 13.3).
+ *
+ * Since: 1.52
+ */
+void
+pango_hb_font_map_set_resolution (PangoHbFontMap *self,
+                                  double          dpi)
+{
+  self->dpi = dpi;
+  clear_caches (self);
+}
+
+/* }}} */
+
+/* vim:set foldmethod=marker expandtab: */
diff --git a/pango/pango-hbfontmap.h b/pango/pango-hbfontmap.h
new file mode 100644
index 00000000..8d5c4050
--- /dev/null
+++ b/pango/pango-hbfontmap.h
@@ -0,0 +1,51 @@
+/* Pango
+ *
+ * Copyright (C) 2021 Matthias Clasen
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.         See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#pragma once
+
+#include <pango/pango-types.h>
+#include <pango/pango-font.h>
+#include <pango/pango-fontmap.h>
+#include <pango/pango-hbface.h>
+#include <hb.h>
+
+G_BEGIN_DECLS
+
+#define PANGO_TYPE_HB_FONT_MAP   (pango_hb_font_map_get_type ())
+
+PANGO_AVAILABLE_IN_1_52
+PANGO_DECLARE_INTERNAL_TYPE (PangoHbFontMap, pango_hb_font_map, PANGO, HB_FONT_MAP, PangoFontMap)
+
+PANGO_AVAILABLE_IN_1_52
+PangoHbFontMap *        pango_hb_font_map_new                   (void);
+
+PANGO_AVAILABLE_IN_1_52
+void                    pango_hb_font_map_add_file              (PangoHbFontMap *self,
+                                                                 const char     *file);
+
+PANGO_AVAILABLE_IN_1_52
+void                    pango_hb_font_map_add_face              (PangoHbFontMap *self,
+                                                                 PangoHbFace    *face);
+
+PANGO_AVAILABLE_IN_1_52
+void                    pango_hb_font_map_set_resolution        (PangoHbFontMap *self,
+                                                                 double          dpi);
+
+G_END_DECLS
diff --git a/pango/pango.h b/pango/pango.h
index ac4e2a6a..048a1f1d 100644
--- a/pango/pango.h
+++ b/pango/pango.h
@@ -41,6 +41,7 @@
 #include <pango/pango-gravity.h>
 #include <pango/pango-hbface.h>
 #include <pango/pango-hbfont.h>
+#include <pango/pango-hbfontmap.h>
 #include <pango/pango-item.h>
 #include <pango/pango-language.h>
 #include <pango/pango-layout.h>