From 69e1c3c3528c78f68fa76ad8efa9501ea9b7834c Mon Sep 17 00:00:00 2001
From: Khaled Hosny <khaled@aliftype.com>
Date: Fri, 28 Feb 2025 00:25:17 +0200
Subject: [PATCH] [ft] Add hb_ft_font_get_ft_face()

A new name for hb_ft_font_get_face(), which is now deprecated.

Fixes  https://github.com/harfbuzz/harfbuzz/issues/5084
---
 docs/harfbuzz-sections.txt |  1 +
 src/hb-ft.cc               | 37 +++++++++++++++++++++++++++++++------
 src/hb-ft.h                |  9 ++++++++-
 test/api/test-ft.c         |  2 +-
 util/helper-cairo-ft.hh    |  2 +-
 5 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt
index cfacdf1ec..b3c5a53c1 100644
--- a/docs/harfbuzz-sections.txt
+++ b/docs/harfbuzz-sections.txt
@@ -524,6 +524,7 @@ hb_ft_face_create_from_file_or_fail
 hb_ft_font_create
 hb_ft_font_create_referenced
 hb_ft_font_changed
+hb_ft_font_get_ft_face
 hb_ft_font_get_face
 hb_ft_font_lock_face
 hb_ft_font_unlock_face
diff --git a/src/hb-ft.cc b/src/hb-ft.cc
index 3cbf0a5dd..724a4193f 100644
--- a/src/hb-ft.cc
+++ b/src/hb-ft.cc
@@ -278,6 +278,33 @@ hb_ft_font_get_load_flags (hb_font_t *font)
   return ft_font->load_flags;
 }
 
+/**
+ * hb_ft_font_get_ft_face: (skip)
+ * @font: #hb_font_t to work upon
+ *
+ * Fetches the FT_Face associated with the specified #hb_font_t
+ * font object.
+ *
+ * This function works with #hb_font_t objects created by
+ * hb_ft_font_create() or hb_ft_font_create_referenced().
+ *
+ * Return value: (nullable): the FT_Face found or `NULL`
+ *
+ * XSince: REPLACEME
+ **/
+FT_Face
+hb_ft_font_get_ft_face (hb_font_t *font)
+{
+  if (unlikely (font->destroy != (hb_destroy_func_t) _hb_ft_font_destroy))
+    return nullptr;
+
+  const hb_ft_font_t *ft_font = (const hb_ft_font_t *) font->user_data;
+
+  return ft_font->ft_face;
+}
+
+#ifndef HB_DISABLE_DEPRECATED
+
 /**
  * hb_ft_font_get_face: (skip)
  * @font: #hb_font_t to work upon
@@ -291,18 +318,16 @@ hb_ft_font_get_load_flags (hb_font_t *font)
  * Return value: (nullable): the FT_Face found or `NULL`
  *
  * Since: 0.9.2
+ * XDeprecated: REPLACEME: Use hb_ft_font_get_ft_face() instead.
  **/
 FT_Face
 hb_ft_font_get_face (hb_font_t *font)
 {
-  if (unlikely (font->destroy != (hb_destroy_func_t) _hb_ft_font_destroy))
-    return nullptr;
-
-  const hb_ft_font_t *ft_font = (const hb_ft_font_t *) font->user_data;
-
-  return ft_font->ft_face;
+  return hb_ft_font_get_ft_face (font);
 }
 
+#endif
+
 /**
  * hb_ft_font_lock_face: (skip)
  * @font: #hb_font_t to work upon
diff --git a/src/hb-ft.h b/src/hb-ft.h
index 8cf14dc39..42bfb4f46 100644
--- a/src/hb-ft.h
+++ b/src/hb-ft.h
@@ -111,7 +111,7 @@ HB_EXTERN hb_font_t *
 hb_ft_font_create_referenced (FT_Face ft_face);
 
 HB_EXTERN FT_Face
-hb_ft_font_get_face (hb_font_t *font);
+hb_ft_font_get_ft_face (hb_font_t *font);
 
 HB_EXTERN FT_Face
 hb_ft_font_lock_face (hb_font_t *font);
@@ -142,6 +142,13 @@ hb_ft_hb_font_changed (hb_font_t *font);
 HB_EXTERN void
 hb_ft_font_set_funcs (hb_font_t *font);
 
+#ifndef HB_DISABLE_DEPRECATED
+
+HB_DEPRECATED_FOR (hb_ft_font_get_ft_face)
+HB_EXTERN FT_Face
+hb_ft_font_get_face (hb_font_t *font);
+
+#endif
 
 HB_END_DECLS
 
diff --git a/test/api/test-ft.c b/test/api/test-ft.c
index 8154ff403..d12f42487 100644
--- a/test/api/test-ft.c
+++ b/test/api/test-ft.c
@@ -87,7 +87,7 @@ test_native_ft_basic (void)
 
   font = hb_ft_font_create_referenced (ft_face);
 
-  ft_face2 = hb_ft_font_get_face (font);
+  ft_face2 = hb_ft_font_get_ft_face (font);
 
   g_assert_true (ft_face2 == ft_face);
 
diff --git a/util/helper-cairo-ft.hh b/util/helper-cairo-ft.hh
index 386cd9e0a..634659a1a 100644
--- a/util/helper-cairo-ft.hh
+++ b/util/helper-cairo-ft.hh
@@ -50,7 +50,7 @@ helper_cairo_create_ft_font_face (const font_options_t *font_opts)
   /* We cannot use the FT_Face from hb_font_t, as doing so will confuse hb_font_t because
    * cairo will reset the face size.  As such, create new face...
    * TODO Perhaps add API to hb-ft to encapsulate this code. */
-  FT_Face ft_face = nullptr;//hb_ft_font_get_face (font);
+  FT_Face ft_face = nullptr;//hb_ft_font_get_ft_face (font);
   if (!ft_face)
   {
     if (!ft_library)