SDL_ttf: Added TTF_GetFontProperties()

From c4383450236973c878ba84f323cc8c86751b2d36 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Thu, 26 Sep 2024 19:37:13 -0700
Subject: [PATCH] Added TTF_GetFontProperties()

You can now directly get the number of font faces from TTF_PROP_FONT_FACE_POINTER, so TTF_FontFaces() is obsoleted.
---
 build-scripts/SDL_migration.cocci |  5 -----
 docs/README-migration.md          |  3 ++-
 include/SDL3_ttf/SDL_ttf.h        | 31 +++++++++++++++++++------------
 src/SDL_ttf.c                     | 14 ++++++++++++++
 src/SDL_ttf.sym                   |  2 +-
 5 files changed, 36 insertions(+), 19 deletions(-)

diff --git a/build-scripts/SDL_migration.cocci b/build-scripts/SDL_migration.cocci
index df7daba6..81b3788f 100644
--- a/build-scripts/SDL_migration.cocci
+++ b/build-scripts/SDL_migration.cocci
@@ -127,11 +127,6 @@
   (...)
 @@
 @@
-- TTF_FontFaces
-+ TTF_GetNumFontFaces
-  (...)
-@@
-@@
 - TTF_FontFaceIsFixedWidth
 + TTF_FontIsFixedWidth
   (...)
diff --git a/docs/README-migration.md b/docs/README-migration.md
index 59df1fa4..422011fc 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -42,7 +42,6 @@ The following functions have been renamed:
 * TTF_FontFaceFamilyName() => TTF_GetFontFamilyName()
 * TTF_FontFaceIsFixedWidth() => TTF_FontIsFixedWidth()
 * TTF_FontFaceStyleName() => TTF_GetFontStyleName()
-* TTF_FontFaces() => TTF_GetNumFontFaces()
 * TTF_FontHeight() => TTF_GetFontHeight()
 * TTF_FontLineSkip() => TTF_GetFontLineSkip()
 * TTF_GetFontWrappedAlign() => TTF_GetFontWrapAlignment()
@@ -76,6 +75,7 @@ The following functions have been removed:
 * TTF_OpenFontDPIIO() - replaced with TTF_OpenFontWithProperties()
 * TTF_OpenFontIndex() - replaced with TTF_OpenFontWithProperties()
 * TTF_OpenFontIndexDPI() - replaced with TTF_OpenFontWithProperties()
+* TTF_FontFaces() - can be retrieved from the font FT_Face, available in TTF_PROP_FONT_FACE_POINTER
 * TTF_OpenFontIndexDPIIO() - replaced with TTF_OpenFontWithProperties()
 * TTF_OpenFontIndexIO() - replaced with TTF_OpenFontWithProperties()
 * TTF_RenderUNICODE_Blended()
@@ -87,6 +87,7 @@ The following functions have been removed:
 * TTF_RenderUNICODE_Solid()
 * TTF_RenderUNICODE_Solid_Wrapped()
 * TTF_SizeUNICODE()
+
 The following symbols have been renamed:
 * TTF_WRAPPED_ALIGN_CENTER => TTF_HORIZONTAL_ALIGN_CENTER
 * TTF_WRAPPED_ALIGN_LEFT => TTF_HORIZONTAL_ALIGN_LEFT
diff --git a/include/SDL3_ttf/SDL_ttf.h b/include/SDL3_ttf/SDL_ttf.h
index 323563b5..9d6e8c5f 100644
--- a/include/SDL3_ttf/SDL_ttf.h
+++ b/include/SDL3_ttf/SDL_ttf.h
@@ -233,6 +233,25 @@ extern SDL_DECLSPEC TTF_Font * SDLCALL TTF_OpenFontWithProperties(SDL_Properties
 #define TTF_PROP_FONT_HORIZONTAL_DPI_NUMBER         "SDL_ttf.font.hdpi"
 #define TTF_PROP_FONT_VERTICAL_DPI_NUMBER           "SDL_ttf.font.vdpi"
 
+/**
+ * Get the properties associated with a font.
+ *
+ * The following read-only properties are provided by SDL:
+ *
+ * - `TTF_PROP_FONT_FACE_POINTER`: the FT_Face associated with the font.
+ *
+ * \param font the font to query.
+ * \returns a valid property ID on success or 0 on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern SDL_DECLSPEC SDL_PropertiesID SDLCALL TTF_GetFontProperties(TTF_Font *font);
+
+#define TTF_PROP_FONT_FACE_POINTER                  "SDL_ttf.font.face"
+
 /**
  * Set a font's size dynamically.
  *
@@ -532,18 +551,6 @@ extern SDL_DECLSPEC bool SDLCALL TTF_GetFontKerning(const TTF_Font *font);
  */
 extern SDL_DECLSPEC void SDLCALL TTF_SetFontKerning(TTF_Font *font, bool enabled);
 
-/**
- * Query the number of faces of a font.
- *
- * \param font the font to query.
- * \returns the number of FreeType font faces.
- *
- * \threadsafety It is safe to call this function from any thread.
- *
- * \since This function is available since SDL_ttf 3.0.0.
- */
-extern SDL_DECLSPEC int SDLCALL TTF_GetNumFontFaces(const TTF_Font *font);
-
 /**
  * Query whether a font is fixed-width.
  *
diff --git a/src/SDL_ttf.c b/src/SDL_ttf.c
index fb6c928e..e8729e4f 100644
--- a/src/SDL_ttf.c
+++ b/src/SDL_ttf.c
@@ -223,6 +223,9 @@ struct TTF_Font {
     /* Freetype2 maintains all sorts of useful info itself */
     FT_Face face;
 
+    /* Properties exposed to the application */
+    SDL_PropertiesID props;
+
     /* We'll cache these ourselves */
     int height;
     int ascent;
@@ -1846,6 +1849,13 @@ TTF_Font *TTF_OpenFontWithProperties(SDL_PropertiesID props)
     }
     face = font->face;
 
+    font->props = SDL_CreateProperties();
+    if (!font->props) {
+        TTF_CloseFont(font);
+        return NULL;
+    }
+    SDL_SetPointerProperty(font->props, TTF_PROP_FONT_FACE_POINTER, face);
+
     /* Set charmap for loaded font */
     found = 0;
 #if 0 /* Font debug code */
@@ -1919,6 +1929,7 @@ TTF_Font *TTF_OpenFontWithProperties(SDL_PropertiesID props)
         TTF_CloseFont(font);
         return NULL;
     }
+
     return font;
 }
 
@@ -2727,6 +2738,9 @@ void TTF_CloseFont(TTF_Font *font)
         hb_font_destroy(font->hb_font);
 #endif
         Flush_Cache(font);
+        if (font->props) {
+            SDL_DestroyProperties(font->props);
+        }
         if (font->face) {
             FT_Done_Face(font->face);
         }
diff --git a/src/SDL_ttf.sym b/src/SDL_ttf.sym
index c746ffb1..3a49d033 100644
--- a/src/SDL_ttf.sym
+++ b/src/SDL_ttf.sym
@@ -12,6 +12,7 @@ SDL3_ttf_0.0.0 {
     TTF_GetFontKerning;
     TTF_GetFontLineSkip;
     TTF_GetFontOutline;
+    TTF_GetFontProperties;
     TTF_GetFontSDF;
     TTF_GetFontStyle;
     TTF_GetFontStyleName;
@@ -20,7 +21,6 @@ SDL3_ttf_0.0.0 {
     TTF_GetGlyphKerning;
     TTF_GetGlyphMetrics;
     TTF_GetHarfBuzzVersion;
-    TTF_GetNumFontFaces;
     TTF_Init;
     TTF_MeasureText;
     TTF_OpenFont;