Add charmap iteration API

This commit adds a set of APIs for iterating over the set of codepoints
for which the font provides a glyph. This implementation calls FreeType
directly to iterate over the charmap of font->face.

This is intended to be used in for loops as follows:

    for (Uint32 ch = TTF_GetFirstFontChar(font); ch != UINT32_MAX;
         ch = TTF_GetNextFontChar(font)) {
        /* do something... */
    }

Author: mcendu

include/SDL3_ttf/SDL_ttf.h

@@ -1132,6 +1132,38 @@ extern SDL_DECLSPEC bool SDLCALL TTF_SetFontLanguage(TTF_Font *font, const char
  */
 extern SDL_DECLSPEC bool SDLCALL TTF_FontHasGlyph(TTF_Font *font, Uint32 ch);
 
+/**
+ * Get the first UNICODE codepoint for which the font provides a glyph.
+ *
+ * \param font the font to query.
+ * \returns the first codepoint, or UINT32_MAX if the font's charmap is empty.
+ *
+ * \threadsafety This function should be called on the thread that created the
+ *               font.
+ *
+ * \since This function is available since SDL_ttf 3.4.0.
+ *
+ * \sa TTF_GetNextFontChar
+ */
+extern SDL_DECLSPEC Uint32 SDLCALL TTF_GetFirstFontChar(TTF_Font *font);
+
+/**
+ * Get the next UNICODE codepoint for which the font provides a glyph.
+ *
+ * \param font the font to query.
+ * \param ch the current codepoint.
+ * \returns the next codepoint, or UINT32_MAX if the end of the font's charmap
+ *          is reached.
+ *
+ * \threadsafety This function should be called on the thread that created the
+ *               font.
+ *
+ * \since This function is available since SDL_ttf 3.4.0.
+ *
+ * \sa TTF_GetFirstFontChar
+ */
+extern SDL_DECLSPEC Uint32 SDLCALL TTF_GetNextFontChar(TTF_Font *font, Uint32 ch);
+
 /**
  * The type of data in a glyph image
  *

src/SDL_ttf.c

@@ -3160,6 +3160,32 @@ bool TTF_FontHasGlyph(TTF_Font *font, Uint32 ch)
     return (get_char_index_fallback(font, ch, NULL, NULL) > 0);
 }
 
+Uint32 TTF_GetFirstFontChar(TTF_Font *font)
+{
+    TTF_CHECK_FONT(font, UINT32_MAX);
+
+    FT_UInt idx;
+    Uint32 ch = (Uint32)FT_Get_First_Char(font->face, &idx);
+
+    if (idx == 0) {
+        return UINT32_MAX;
+    }
+    return ch;
+}
+
+Uint32 TTF_GetNextFontChar(TTF_Font *font, Uint32 ch)
+{
+    TTF_CHECK_FONT(font, UINT32_MAX);
+
+    FT_UInt idx;
+    Uint32 next = (Uint32)FT_Get_Next_Char(font->face, ch, &idx);
+
+    if (idx == 0) {
+        return UINT32_MAX;
+    }
+    return next;
+}
+
 SDL_Surface *TTF_GetGlyphImage(TTF_Font *font, Uint32 ch, TTF_ImageType *image_type)
 {
     FT_UInt idx;

src/SDL_ttf.exports

@@ -118,4 +118,6 @@ _TTF_Version
 _TTF_WasInit
 _TTF_SetFontCharSpacing
 _TTF_GetFontCharSpacing
+_TTF_GetFirstFontChar
+_TTF_GetNextFontChar
 # extra symbols go here (don't modify this line)

src/SDL_ttf.sym

@@ -119,6 +119,8 @@ SDL3_ttf_0.0.0 {
     TTF_WasInit;
     TTF_SetFontCharSpacing;
     TTF_GetFontCharSpacing;
+    TTF_GetFirstFontChar;
+    TTF_GetNextFontChar;
     # extra symbols go here (don't modify this line)
   local: *;
 };