[pango/pango2-color-palette: 21/22] Add Pango2HbFaceBuilder

[Matthias Clasen <matthiasc src gnome org>]

commit 6803332fe44c0e26669e12c78d2c543146f66e74
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Jul 1 23:19:50 2022 -0400

    Add Pango2HbFaceBuilder
    
    This can replace some of the clunky constructors,
    and is more extensible, going forward.

 pango2/pango-fontmap.c |  29 ++-
 pango2/pango-hbface.c  | 519 +++++++++++++++++++++++++++++--------------------
 pango2/pango-hbface.h  |  57 ++++--
 tests/test-common.c    |   8 +-
 tests/testhbfont.c     |  48 ++++-
 5 files changed, 428 insertions(+), 233 deletions(-)
---
diff --git a/pango2/pango-fontmap.c b/pango2/pango-fontmap.c
index 275eb0822..32dcd9286 100644
--- a/pango2/pango-fontmap.c
+++ b/pango2/pango-fontmap.c
@@ -269,6 +269,7 @@ add_style_variation (Pango2HbFamily *family,
 {
   Pango2Matrix italic_matrix = { 1, 0.2, 0, 1, 0, 0 };
   Pango2FontDescription *desc;
+  Pango2HbFaceBuilder *builder;
   Pango2HbFace *variation;
 
   desc = pango2_font_description_new ();
@@ -276,13 +277,31 @@ add_style_variation (Pango2HbFamily *family,
   pango2_font_description_set_style (desc, style);
   pango2_font_description_set_weight (desc, weight);
 
-  variation = pango2_hb_face_new_synthetic (face,
-                                            style == PANGO2_STYLE_ITALIC ? &italic_matrix : NULL,
-                                            weight == PANGO2_WEIGHT_BOLD,
-                                            NULL,
-                                            desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_transform (builder, style == PANGO2_STYLE_ITALIC ? &italic_matrix : NULL);
+  pango2_hb_face_builder_set_embolden (builder, weight == PANGO2_WEIGHT_BOLD);
+  pango2_hb_face_builder_set_description (builder, desc);
+  if (style == PANGO2_STYLE_ITALIC)
+    {
+      if (weight == PANGO2_WEIGHT_BOLD)
+        pango2_hb_face_builder_set_name (builder, "Bold Italic");
+      else
+        pango2_hb_face_builder_set_name (builder, "Italic");
+    }
+  else
+    {
+      if (weight == PANGO2_WEIGHT_BOLD)
+        pango2_hb_face_builder_set_name (builder, "Bold");
+      else
+        pango2_hb_face_builder_set_name (builder, "Regular");
+    }
+
+  variation = pango2_hb_face_builder_get_face (builder);
+
   pango2_hb_family_add_face (family, PANGO2_FONT_FACE (variation));
 
+  pango2_hb_face_builder_free (builder);
+
   pango2_font_description_free (desc);
 }
 
diff --git a/pango2/pango-hbface.c b/pango2/pango-hbface.c
index 5f8486b21..dbe68e176 100644
--- a/pango2/pango-hbface.c
+++ b/pango2/pango-hbface.c
@@ -279,38 +279,6 @@ ensure_faceid (Pango2HbFace *self)
   g_free (str);
 }
 
-static const char *
-style_from_font_description (const Pango2FontDescription *desc)
-{
-  Pango2Style style = pango2_font_description_get_style (desc);
-  Pango2Weight weight = pango2_font_description_get_weight (desc);
-
-  switch (style)
-    {
-    case PANGO2_STYLE_ITALIC:
-      if (weight == PANGO2_WEIGHT_BOLD)
-        return "Bold Italic";
-      else
-        return "Italic";
-      break;
-    case PANGO2_STYLE_OBLIQUE:
-      if (weight == PANGO2_WEIGHT_BOLD)
-        return "Bold Oblique";
-      else
-        return "Oblique";
-      break;
-    case PANGO2_STYLE_NORMAL:
-      if (weight == PANGO2_WEIGHT_BOLD)
-        return "Bold";
-      else
-        return "Regular";
-      break;
-    default: ;
-    }
-
-  return NULL;
-}
-
 /* }}} */
 /* {{{ Pango2FontFace implementation */
 
@@ -660,7 +628,7 @@ pango2_hb_face_set_matrix (Pango2HbFace       *self,
 }
 
 /* }}} */
- /* {{{ Public API */
+  /* {{{ Public API */
 
 /**
  * pango2_hb_face_new_from_hb_face:
@@ -782,179 +750,6 @@ pango2_hb_face_new_from_file (const char                  *file,
   return self;
 }
 
-/**
- * pango2_hb_face_new_synthetic:
- * @face: a `Pango2HbFace`
- * @transform: (nullable): the transform to apply
- * @embolden: `TRUE` to render the font bolder
- * @name: (nullable): name for the face
- * @description: a `Pango2FontDescription` to override fields from @face's description
- *
- * Creates a new `Pango2HbFace` that is a synthetic variant of @face.
- *
- * Here, 'synthetic' means that the variant is implemented by rendering
- * the glyphs differently, not by using data from the original @face.
- * See [method@Pango2.HbFace.new_instance] for that.
- *
- * @transform can be used to specify a non-trivial font matrix for creating
- * synthetic italics or synthetic condensed variants of an existing face.
- *
- * If @embolden is `TRUE`, Pango will render the glyphs bolder, creating
- * a synthetic bold variant of the face.
- *
- * If a @name is not specified, the name for the face will be derived
- * from the @description.
- *
- * Apart from setting the style that this face will be used for,
- * @description can provide an alternative family name. This can
- * be used to create generic aliases such as 'sans' or 'monospace'.
- *
- * Note that only the following fields in @description should be set:
- *
- * + style or stretch, to indicate a transformed style
- * + weight, to indicate a bolder weight
- * + family, to provide an alternative family name
- *
- * [method@Pango2.FontFace.is_synthesized] will return `TRUE` for objects
- * created by this function.
- *
- * Returns: (transfer full): a newly created `Pango2HbFace`
- */
-Pango2HbFace *
-pango2_hb_face_new_synthetic (Pango2HbFace                *face,
-                              const Pango2Matrix          *transform,
-                              gboolean                     embolden,
-                              const char                  *name,
-                              const Pango2FontDescription *description)
-{
-  Pango2HbFace *self;
-  Pango2FontDescription *desc;
-
-  g_return_val_if_fail (PANGO2_IS_HB_FACE (face), NULL);
-  g_return_val_if_fail (description != NULL, NULL);
-  g_return_val_if_fail ((pango2_font_description_get_set_fields (description) &
-                         ~(PANGO2_FONT_MASK_FAMILY|
-                           PANGO2_FONT_MASK_STYLE|
-                           PANGO2_FONT_MASK_STRETCH|
-                           PANGO2_FONT_MASK_WEIGHT)) == 0, NULL);
-
-  self = g_object_new (PANGO2_TYPE_HB_FACE, NULL);
-
-  self->file = g_strdup (face->file);
-  if (face->face)
-    self->face = hb_face_reference (face->face);
-
-  self->index = face->index;
-  self->instance_id = face->instance_id;
-  self->variations = g_memdup2 (face->variations, sizeof (hb_variation_t) * face->n_variations);
-  self->n_variations = face->n_variations;
-
-  if (transform)
-    pango2_hb_face_set_matrix (self, transform);
-
-  self->embolden = embolden;
-  self->synthetic = self->embolden || (self->transform != NULL);
-
-  desc = pango2_font_description_copy (PANGO2_FONT_FACE (face)->description);
-  pango2_font_description_merge (desc, description, TRUE);
-
-  if (!name)
-    name = style_from_font_description (desc);
-
-  set_name_and_description (self, name, desc);
-
-  pango2_hb_face_set_language_set (self, face->languages);
-
-  pango2_font_description_free (desc);
-
-  return self;
-}
-
-/**
- * pango2_hb_face_new_instance:
- * @face: a `Pango2HbFace`
- * @variations: (nullable) (array length=n_variations): font variations to apply
- * @n_variations: length of @variations
- * @name: (nullable): name for the face
- * @description: a `Pango2FontDescription` to override fields from @face's description
- *
- * Creates a new `Pango2HbFace` that is a variant of @face.
- *
- * The @variations provide values for variation axes of @face. Axes that
- * are not included in @variations will keep the values they have in @face.
- * @variations that refer to axes that the face does not have are ignored.
- *
- * Conceptually, this is similar to a named instance of the face, except
- * that the mapping of the name to a set of coordinates on the variation
- * axes is provided externally, and not by the face itself.
- *
- * If a @name is not specified, the name for the face will be derived
- * from the @description.
- *
- * Apart from setting the style that this face will be used for,
- * @description can provide an alternative family name. This can
- * be used to create generic aliases such as 'sans' or 'monospace'.
- *
- * Note that only the following fields in @description should be set:
- * - style or stretch, to indicate a transformed style
- * - weight, to indicate a bolder weight
- * - family, to provide an alternative family name
- *
- * Returns: (transfer full): a newly created `Pango2HbFace`
- */
-Pango2HbFace *
-pango2_hb_face_new_instance (Pango2HbFace                *face,
-                             const hb_variation_t        *variations,
-                             unsigned int                 n_variations,
-                             const char                  *name,
-                             const Pango2FontDescription *description)
-{
-  Pango2HbFace *self;
-  Pango2FontDescription *desc;
-
-  g_return_val_if_fail (PANGO2_IS_HB_FACE (face), NULL);
-  g_return_val_if_fail (description != NULL, NULL);
-  g_return_val_if_fail ((pango2_font_description_get_set_fields (description) &
-                         ~(PANGO2_FONT_MASK_FAMILY|
-                           PANGO2_FONT_MASK_STYLE|
-                           PANGO2_FONT_MASK_STRETCH|
-                           PANGO2_FONT_MASK_WEIGHT)) == 0, NULL);
-
-  self = g_object_new (PANGO2_TYPE_HB_FACE, NULL);
-
-  self->file = g_strdup (face->file);
-  if (face->face)
-    self->face = hb_face_reference (face->face);
-
-  self->index = face->index;
-  self->instance_id = face->instance_id;
-
-  if (face->transform)
-    {
-      self->transform = g_memdup2 (face->transform, sizeof (Pango2Matrix));
-      self->x_scale = face->x_scale;
-      self->y_scale = face->y_scale;
-    }
-
-  self->embolden = face->embolden;
-  self->synthetic = self->embolden || (self->transform != NULL);
-
-  self->variations = g_memdup2 (variations, sizeof (hb_variation_t) * n_variations);
-  self->n_variations = n_variations;
-
-  desc = pango2_font_description_copy (PANGO2_FONT_FACE (face)->description);
-  pango2_font_description_merge (desc, description, TRUE);
-
-  if (!name)
-    name = style_from_font_description (desc);
-
-  set_name_and_description (self, name, desc);
-
-  pango2_font_description_free (desc);
-
-  return self;
-}
-
 /**
  * pango2_hb_face_get_hb_face:
  * @self: a `Pango2HbFace`
@@ -1082,6 +877,318 @@ pango2_hb_face_get_transform (Pango2HbFace *self)
   return self->transform;
 }
 
+/* }}} */
+/* {{{ Pango2HbFaceBuilder */
+
+/**
+ * Pango2HbFaceBuilder:
+ *
+ * An auxiliary object to build `Pango2HbFace` objects.
+ */
+
+struct _Pango2HbFaceBuilder {
+  hb_face_t *hb_face;
+  Pango2HbFace *face;
+  Pango2Matrix *transform;
+  gboolean embolden;
+  int instance_id;
+  hb_variation_t *variations;
+  unsigned int n_variations;
+  char *name;
+  Pango2FontDescription *description;
+};
+
+G_DEFINE_BOXED_TYPE (Pango2HbFaceBuilder, pango2_hb_face_builder,
+                     pango2_hb_face_builder_copy,
+                     pango2_hb_face_builder_free);
+
+static Pango2HbFaceBuilder *
+face_builder_new (void)
+{
+  Pango2HbFaceBuilder *builder;
+
+  builder = g_new (Pango2HbFaceBuilder, 1);
+  builder->hb_face = NULL;
+  builder->face = NULL;
+  builder->transform = NULL;
+  builder->embolden = FALSE;
+  builder->instance_id = 0;
+  builder->variations = NULL;
+  builder->n_variations = 0;
+  builder->name = NULL;
+  builder->description = NULL;
+
+  return builder;
+}
+
+/**
+ * pango2_hb_face_builder_copy:
+ * @src: a `Pango2HbFaceBuilder`
+ *
+ * Copy a `Pango2HbFaceBuilder`.
+ *
+ * Returns: (transfer full): a copy of @src
+ */
+Pango2HbFaceBuilder *
+pango2_hb_face_builder_copy (const Pango2HbFaceBuilder *src)
+{
+  Pango2HbFaceBuilder *builder;
+
+  builder = face_builder_new ();
+  if (src->face)
+    builder->face = g_object_ref (src->face);
+  if (src->hb_face)
+    builder->hb_face = hb_face_reference (src->hb_face);
+  builder->transform = g_memdup2 (src->transform, sizeof (Pango2Matrix));
+  builder->embolden = src->embolden;
+  builder->instance_id = src->instance_id;
+  builder->variations = g_memdup2 (src->variations, sizeof (hb_variation_t) * src->n_variations);
+  builder->n_variations = src->n_variations;
+  builder->name = g_strdup (src->name);
+  if (src->description)
+    builder->description = pango2_font_description_copy_static (src->description);
+
+  return builder;
+}
+
+/**
+ * pango2_hb_face_builder_free:
+ * @builder: a `Pango2HbFaceBuilder`
+ *
+ * Frees the `PangoHbFaceBuilder`.
+ */
+void
+pango2_hb_face_builder_free (Pango2HbFaceBuilder *builder)
+{
+  if (builder->hb_face)
+    hb_face_destroy (builder->hb_face);
+  if (builder->face)
+    g_object_unref (builder->face);
+  g_free (builder->transform);
+  g_free (builder->variations);
+  g_free (builder->name);
+  if (builder->description)
+    pango2_font_description_free (builder->description);
+
+  g_free (builder);
+}
+
+/**
+ * pango2_hb_face_builder_new_for_hb_face:
+ * @hb_face: a `hb_face_t`
+ *
+ * Creates a new `Pango2HbFaceBuilder` that will
+ * produce `Pango2HbFace` objects wrapping @hb_face.
+ *
+ * Returns: (transfer full): a new `Pango2HbFaceBuilder`
+ */
+Pango2HbFaceBuilder *
+pango2_hb_face_builder_new_for_hb_face (hb_face_t *hb_face)
+{
+  Pango2HbFaceBuilder *builder;
+
+  g_return_val_if_fail (hb_face_is_immutable (hb_face), NULL);
+
+  builder = face_builder_new ();
+  builder->hb_face = hb_face_reference (hb_face);
+
+  return builder;
+}
+
+/**
+ * pango2_hb_face_builder_new:
+ * @face: a `Pango2HbFace`
+ *
+ * Creates a new `Pango2HbFaceBuilder` that will
+ * produce `Pango2HbFace` objects wrapping @face.
+ *
+ * Returns: (transfer full): a new `Pango2HbFaceBuilder`
+ */
+Pango2HbFaceBuilder *
+pango2_hb_face_builder_new (Pango2HbFace *face)
+{
+  Pango2FontFace *font_face = PANGO2_FONT_FACE (face);
+  Pango2HbFaceBuilder *builder;
+
+  g_return_val_if_fail (PANGO2_IS_HB_FACE (face), NULL);
+
+  builder = face_builder_new ();
+  builder->face = g_object_ref (face);
+  if (face->transform)
+    {
+      builder->transform = g_memdup2 (face->transform, sizeof (Pango2Matrix));
+      pango2_matrix_scale (builder->transform, face->x_scale, face->y_scale);
+    }
+  builder->embolden = face->embolden;
+  builder->instance_id = face->instance_id;
+  builder->variations = g_memdup2 (face->variations, sizeof (hb_variation_t) * face->n_variations);
+  builder->n_variations = face->n_variations;
+  builder->name = g_strdup (font_face->name);
+  builder->description = pango2_font_description_copy_static (font_face->description);
+
+  return builder;
+}
+
+/**
+ * pango2_hb_face_builder_get_face:
+ * @builder: a `Pango2HbFaceBuilder`
+ *
+ * Gets a new `Pango2HbFace` instance with the current builder data.
+ *
+ * Returns: (transfer full): a new `Pango2HbFace`
+ */
+Pango2HbFace *
+pango2_hb_face_builder_get_face (Pango2HbFaceBuilder *builder)
+{
+  Pango2HbFace *self;
+
+  self = g_object_new (PANGO2_TYPE_HB_FACE, NULL);
+  if (builder->face)
+    {
+      self->file = g_strdup (builder->face->file);
+      self->index = builder->face->index;
+      self->instance_id = builder->face->instance_id;
+      if (builder->face->face)
+        self->face = hb_face_reference (builder->face->face);
+      pango2_hb_face_set_language_set (self, builder->face->languages);
+    }
+  else if (builder->hb_face)
+    {
+       self->face = hb_face_reference (builder->hb_face);
+    }
+
+  self->instance_id = builder->instance_id;
+
+  if (builder->transform)
+    pango2_hb_face_set_matrix (self, builder->transform);
+
+  self->embolden = builder->embolden;
+  self->synthetic = self->embolden || (self->transform != NULL);
+
+  self->variations = g_memdup2 (builder->variations, sizeof (hb_variation_t) * builder->n_variations);
+  self->n_variations = builder->n_variations;
+
+  set_name_and_description (self, builder->name, builder->description);
+
+  return self;
+}
+
+/**
+ * pango2_hb_face_builder_set_instance_id:
+ * @builder: a `Pango2HbFaceBuilder`
+ * @instance_id: named instance id, or -1 for the default instance
+ *   or -2 for no instance
+ *
+ * Sets the instance ID to use for the face.
+ */
+void
+pango2_hb_face_builder_set_instance_id  (Pango2HbFaceBuilder *builder,
+                                         int                  instance_id)
+{
+  g_return_if_fail (instance_id >= -2);
+
+  builder->instance_id = instance_id;
+}
+
+/**
+ * pango2_hb_face_builder_set_name:
+ * @builder: a `Pango2HbFaceBuilder`
+ * @name: (nullable): name for the face
+ *
+ * Sets the name to use for the face.
+ *
+ * If @name is `NULL`, the name of the underlying object is used.
+ */
+void
+pango2_hb_face_builder_set_name (Pango2HbFaceBuilder *builder,
+                                 const char          *name)
+{
+  g_free (builder->name);
+  builder->name = g_strdup (name);
+}
+
+/**
+ * pango2_hb_face_builder_set_description:
+ * @builder: a `Pango2HbFaceBuilder`
+ * @desc: (nullable): `Pango2FontDescription` for the face
+ *
+ * Sets the description to use for the face.
+ *
+ * If @desc is `NULL`, the description of the underlying object is used.
+ */
+void
+pango2_hb_face_builder_set_description (Pango2HbFaceBuilder         *builder,
+                                        const Pango2FontDescription *desc)
+{
+  g_return_if_fail (desc == NULL ||
+                    (pango2_font_description_get_set_fields (desc) &
+                         ~(PANGO2_FONT_MASK_FAMILY|
+                           PANGO2_FONT_MASK_STYLE|
+                           PANGO2_FONT_MASK_STRETCH|
+                           PANGO2_FONT_MASK_WEIGHT)) == 0);
+
+  if (builder->description)
+    pango2_font_description_free (builder->description);
+
+  if (builder->face)
+    builder->description = pango2_font_description_copy (PANGO2_FONT_FACE (builder->face)->description);
+
+  if (desc)
+    {
+      if (builder->description)
+        pango2_font_description_merge (builder->description, desc, TRUE);
+      else
+        builder->description = pango2_font_description_copy (desc);
+    }
+}
+
+/**
+ * pango2_hb_face_builder_set_transform:
+ * @builder: a `Pango2HbFaceBuilder`
+ * @transform: (nullable): `Pango2Matrix` for the font matrix
+ *
+ * Sets the font matrix to use for the face.
+ */
+void
+pango2_hb_face_builder_set_transform (Pango2HbFaceBuilder *builder,
+                                      const Pango2Matrix  *transform)
+{
+  g_free (builder->transform);
+  builder->transform = g_memdup2 (transform, sizeof (Pango2Matrix));
+}
+
+/**
+ * pango2_hb_face_builder_set_embolden:
+ * @builder: a `Pango2HbFaceBuilder`
+ * @embolden: `TRUE` to render the font bolder
+ *
+ * Sets whether the face should be artificially emboldened.
+ */
+void
+pango2_hb_face_builder_set_embolden (Pango2HbFaceBuilder *builder,
+                                     gboolean             embolden)
+{
+  builder->embolden = embolden;
+}
+
+/**
+ * pango2_hb_face_builder_set_variations:
+ * @builder: a `Pango2HbFaceBuilder`
+ * @variations: (nullable) (array length=n_variations): font variations to apply
+ * @n_variations: length of @variations
+ *
+ * Sets variations to use for the face.
+ */
+void
+pango2_hb_face_builder_set_variations (Pango2HbFaceBuilder  *builder,
+                                       const hb_variation_t *variations,
+                                       unsigned int          n_variations)
+{
+  g_free (builder->variations);
+  builder->variations = g_memdup2 (variations, sizeof (hb_variation_t) * n_variations);
+  builder->n_variations = n_variations;
+}
+
 /* }}} */
 
 /* vim:set foldmethod=marker expandtab: */
diff --git a/pango2/pango-hbface.h b/pango2/pango-hbface.h
index 2d4662d7a..b110ff99e 100644
--- a/pango2/pango-hbface.h
+++ b/pango2/pango-hbface.h
@@ -44,20 +44,6 @@ Pango2HbFace *          pango2_hb_face_new_from_file     (const char
                                                           const char                  *name,
                                                           const Pango2FontDescription *description);
 
-PANGO2_AVAILABLE_IN_ALL
-Pango2HbFace *          pango2_hb_face_new_synthetic     (Pango2HbFace                *face,
-                                                          const Pango2Matrix          *transform,
-                                                          gboolean                     embolden,
-                                                          const char                  *name,
-                                                          const Pango2FontDescription *description);
-
-PANGO2_AVAILABLE_IN_ALL
-Pango2HbFace *          pango2_hb_face_new_instance      (Pango2HbFace                *face,
-                                                          const hb_variation_t        *variations,
-                                                          unsigned int                 n_variations,
-                                                          const char                  *name,
-                                                          const Pango2FontDescription *description);
-
 PANGO2_AVAILABLE_IN_ALL
 hb_face_t *             pango2_hb_face_get_hb_face       (Pango2HbFace                *self);
 
@@ -80,4 +66,47 @@ gboolean                pango2_hb_face_get_embolden      (Pango2HbFace
 PANGO2_AVAILABLE_IN_ALL
 const Pango2Matrix *    pango2_hb_face_get_transform     (Pango2HbFace                *self);
 
+
+typedef struct _Pango2HbFaceBuilder Pango2HbFaceBuilder;
+
+#define PANGO2_TYPE_HB_FACE_BUILDER (pango2_hb_face_builder_get_type ())
+
+PANGO2_AVAILABLE_IN_ALL
+GType                   pango2_hb_face_builder_get_type         (void) G_GNUC_CONST;
+
+PANGO2_AVAILABLE_IN_ALL
+Pango2HbFaceBuilder *   pango2_hb_face_builder_copy             (const Pango2HbFaceBuilder   *src);
+
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_free             (Pango2HbFaceBuilder         *builder);
+
+PANGO2_AVAILABLE_IN_ALL
+Pango2HbFaceBuilder *   pango2_hb_face_builder_new              (Pango2HbFace                *face);
+
+PANGO2_AVAILABLE_IN_ALL
+Pango2HbFaceBuilder *   pango2_hb_face_builder_new_for_hb_face  (hb_face_t                   *hb_face);
+
+PANGO2_AVAILABLE_IN_ALL
+Pango2HbFace *          pango2_hb_face_builder_get_face         (Pango2HbFaceBuilder         *builder);
+
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_set_instance_id  (Pango2HbFaceBuilder         *builder,
+                                                                 int                          instance_id);
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_set_name         (Pango2HbFaceBuilder         *builder,
+                                                                 const char                  *name);
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_set_description  (Pango2HbFaceBuilder         *builder,
+                                                                 const Pango2FontDescription *desc);
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_set_transform    (Pango2HbFaceBuilder         *builder,
+                                                                 const Pango2Matrix          *transform);
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_set_embolden     (Pango2HbFaceBuilder         *builder,
+                                                                 gboolean                     embolden);
+PANGO2_AVAILABLE_IN_ALL
+void                    pango2_hb_face_builder_set_variations   (Pango2HbFaceBuilder         *builder,
+                                                                 const hb_variation_t        *variations,
+                                                                 unsigned int                 n_variations);
+
 G_END_DECLS
diff --git a/tests/test-common.c b/tests/test-common.c
index aa51378aa..162a6432b 100644
--- a/tests/test-common.c
+++ b/tests/test-common.c
@@ -351,6 +351,7 @@ add_synthetic_faces (Pango2FontMap *map,
   Pango2Matrix italic_matrix = { 1, 0.2, 0, 1, 0, 0 };
   Pango2HbFace *newface;
   GSList *newfaces, *l;
+  Pango2HbFaceBuilder *builder;
 
   g_assert (g_str_has_suffix (name, ".synthetic"));
 
@@ -391,8 +392,13 @@ add_synthetic_faces (Pango2FontMap *map,
                                                        PANGO2_FONT_MASK_STYLE|
                                                        PANGO2_FONT_MASK_STRETCH|
                                                        PANGO2_FONT_MASK_WEIGHT));
-          newface = pango2_hb_face_new_synthetic (face, &italic_matrix, FALSE, name, desc);
+          builder = pango2_hb_face_builder_new (face);
+          pango2_hb_face_builder_set_transform (builder, &italic_matrix);
+          pango2_hb_face_builder_set_name (builder, name);
+          pango2_hb_face_builder_set_description (builder, desc);
+          newface = pango2_hb_face_builder_get_face (builder);
           newfaces = g_slist_prepend (newfaces, newface);
+          pango2_hb_face_builder_free (builder);
 
           g_free (name);
           pango2_font_description_free (desc);
diff --git a/tests/testhbfont.c b/tests/testhbfont.c
index 88fc3ef68..8bf8de1b6 100644
--- a/tests/testhbfont.c
+++ b/tests/testhbfont.c
@@ -73,6 +73,7 @@ test_hbface_roundtrip (void)
   Pango2FontDescription *desc;
   const int NO_FACEID = ~PANGO2_FONT_MASK_FACEID;
   hb_variation_t v;
+  Pango2HbFaceBuilder *builder;
 
   path = g_test_build_filename (G_TEST_DIST, "fonts", "Cantarell-VF.otf", NULL);
 
@@ -93,7 +94,11 @@ test_hbface_roundtrip (void)
 
   desc = pango2_font_description_new ();
   pango2_font_description_set_style (desc, PANGO2_STYLE_OBLIQUE);
-  face2 = pango2_hb_face_new_synthetic (face, &(Pango2Matrix){ 1, 0.2, 0, 1, 0, 0 }, FALSE, NULL, desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_transform (builder, &(Pango2Matrix){ 1, 0.2, 0, 1, 0, 0 });
+  pango2_hb_face_builder_set_description (builder, desc);
+  face2 = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   pango2_font_description_free (desc);
 
   g_assert_true (PANGO2_IS_HB_FACE (face2));
@@ -113,7 +118,11 @@ test_hbface_roundtrip (void)
 
   desc = pango2_font_description_new ();
   pango2_font_description_set_weight (desc, PANGO2_WEIGHT_BOLD);
-  face2 = pango2_hb_face_new_synthetic (face, NULL, TRUE, NULL, desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_embolden (builder, TRUE);
+  pango2_hb_face_builder_set_description (builder, desc);
+  face2 = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   pango2_font_description_free (desc);
 
   g_assert_true (PANGO2_IS_HB_FACE (face2));
@@ -133,7 +142,10 @@ test_hbface_roundtrip (void)
 
   desc = pango2_font_description_new ();
   pango2_font_description_set_family (desc, "Cantarellagain");
-  face2 = pango2_hb_face_new_synthetic (face, NULL, FALSE, NULL, desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_description (builder, desc);
+  face2 = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   pango2_font_description_free (desc);
 
   g_assert_true (PANGO2_IS_HB_FACE (face2));
@@ -158,7 +170,12 @@ test_hbface_roundtrip (void)
   v.tag = HB_OT_TAG_VAR_AXIS_WEIGHT;
   v.value = 768.;
 
-  face2 = pango2_hb_face_new_instance (face, &v, 1, "Fat", desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_variations (builder, &v, 1);
+  pango2_hb_face_builder_set_name (builder, "Fat");
+  pango2_hb_face_builder_set_description (builder, desc);
+  face2 = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   pango2_font_description_free (desc);
 
   g_assert_true (PANGO2_IS_HB_FACE (face2));
@@ -261,6 +278,7 @@ test_hbfont_describe_variation (void)
   Pango2HbFont *font;
   Pango2FontDescription *desc;
   hb_variation_t v;
+  Pango2HbFaceBuilder *builder;
 
   path = g_test_build_filename (G_TEST_DIST, "fonts", "Cantarell-VF.otf", NULL);
 
@@ -290,7 +308,12 @@ test_hbfont_describe_variation (void)
 
   v.tag = HB_OT_TAG_VAR_AXIS_WEIGHT;
   v.value = 512.;
-  face2 = pango2_hb_face_new_instance (face, &v, 1, "Medium", desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_variations (builder, &v, 1);
+  pango2_hb_face_builder_set_name (builder, "Medium");
+  pango2_hb_face_builder_set_description (builder, desc);
+  face2 = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   g_assert_true (PANGO2_IS_HB_FACE (face));
   pango2_font_description_free (desc);
 
@@ -332,6 +355,7 @@ test_hbfont_faceid (void)
   char *path;
   Pango2HbFace *face, *face2, *face3;
   Pango2FontDescription *desc, *desc2, *desc3;
+  Pango2HbFaceBuilder *builder;
 
   path = g_test_build_filename (G_TEST_DIST, "fonts", "Cantarell-VF.otf", NULL);
 
@@ -339,7 +363,11 @@ test_hbfont_faceid (void)
   face2 = pango2_hb_face_new_from_file (path, 0, 2, NULL, NULL);
   desc = pango2_font_description_new ();
   pango2_font_description_set_weight (desc, PANGO2_WEIGHT_BOLD);
-  face3 = pango2_hb_face_new_synthetic (face, NULL, TRUE, NULL, desc);
+  builder = pango2_hb_face_builder_new (face);
+  pango2_hb_face_builder_set_embolden (builder, TRUE);
+  pango2_hb_face_builder_set_description (builder, desc);
+  face3 = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   pango2_font_description_free (desc);
 
   desc = pango2_font_face_describe (PANGO2_FONT_FACE (face));
@@ -443,6 +471,7 @@ test_hbfont_load_variation (void)
   hb_font_t *hb_font;
   const float *coords;
   unsigned int length;
+  Pango2HbFaceBuilder *builder;
 
   /* Make a Cat family, with the two faces Fat and Wild */
   map = pango2_font_map_new ();
@@ -461,7 +490,12 @@ test_hbfont_load_variation (void)
   pango2_font_description_set_family (desc, "Cat");
   v.tag = HB_OT_TAG_VAR_AXIS_WEIGHT;
   v.value = 624.;
-  face_wild = pango2_hb_face_new_instance (face_fat, &v, 1, "Wild", desc);
+  builder = pango2_hb_face_builder_new (face_fat);
+  pango2_hb_face_builder_set_variations (builder, &v, 1);
+  pango2_hb_face_builder_set_name (builder,  "Wild");
+  pango2_hb_face_builder_set_description (builder,  desc);
+  face_wild = pango2_hb_face_builder_get_face (builder);
+  pango2_hb_face_builder_free (builder);
   pango2_font_description_free (desc);
 
   pango2_font_map_add_face (map, PANGO2_FONT_FACE (face_wild));