Implement TTF_SetFontCharSpacing()

examples/showfont.c

@@ -261,6 +261,18 @@ static void HandleKeyDown(Scene *scene, SDL_Event *event)
         }
         break;
 
+    case SDLK_COMMA:
+        if (event->key.mod & SDL_KMOD_CTRL) {
+            TTF_SetFontCharSpacing(scene->font, TTF_GetFontCharSpacing(scene->font) - 1);
+        }
+        break;
+
+    case SDLK_PERIOD:
+        if (event->key.mod & SDL_KMOD_CTRL) {
+            TTF_SetFontCharSpacing(scene->font, TTF_GetFontCharSpacing(scene->font) + 1);
+        }
+        break;
+
     case SDLK_ESCAPE:
         scene->done = true;
         break;

include/SDL3_ttf/SDL_ttf.h

@@ -969,6 +969,44 @@ extern SDL_DECLSPEC bool SDLCALL TTF_SetFontDirection(TTF_Font *font, TTF_Direct
  */
 extern SDL_DECLSPEC TTF_Direction SDLCALL TTF_GetFontDirection(TTF_Font *font);
 
+/**
+ * Set additional space in pixels to be applied between any two rendered
+ * characters. The spacing value is applied uniformly after each character,
+ * in addition to the normal glyph's advance.
+ * 
+ * Spacing may be a negative value, in which case it will reduce the
+ * distance instead.
+ *
+ * This updates any TTF_Text objects using this font.
+ *
+ * \param font the font to specify a direction for.
+ * \param char_spacing the new spacing value.
+ * \returns true on success or false on failure; call SDL_GetError() for more
+ *          information.
+ *
+ * \threadsafety This function should be called on the thread that created the
+ *               font.
+ *
+ * \since This function is available since SDL_ttf 3.4.0.
+ */
+extern SDL_DECLSPEC bool SDLCALL TTF_SetFontCharSpacing(TTF_Font *font, int spacing);
+
+/**
+ * Get the additional character spacing in pixels to be applied between any two
+ * rendered characters.
+ *
+ * This defaults to 0 if it hasn't been set.
+ *
+ * \param font the font to query.
+ * \returns the character spacing in pixels.
+ *
+ * \threadsafety This function should be called on the thread that created the
+ *               font.
+ *
+ * \since This function is available since SDL_ttf 3.0.0.
+ */
+extern SDL_DECLSPEC int SDLCALL TTF_GetFontCharSpacing(TTF_Font *font);
+
 /**
  * Convert from a 4 character string to a 32-bit tag.
  *

src/SDL_ttf.c

@@ -316,6 +316,7 @@ struct TTF_Font {
 #if !TTF_USE_HARFBUZZ
     bool use_kerning;
 #endif
+    int char_spacing; /* in FP 26.6 */
 
     // Extra width in glyph bounds for text styles
     int glyph_overhang;
@@ -3397,7 +3398,7 @@ static bool CollectGlyphsFromFont(TTF_Font *font, const char *text, size_t lengt
         GlyphPosition *pos = &positions->pos[i];
         pos->font = font;
         pos->index = hb_glyph_info[i].codepoint;
-        pos->x_advance = hb_glyph_position[i].x_advance + advance_if_bold;
+        pos->x_advance = hb_glyph_position[i].x_advance + advance_if_bold + font->char_spacing;
         pos->y_advance = hb_glyph_position[i].y_advance;
         pos->x_offset = hb_glyph_position[i].x_offset;
         pos->y_offset = hb_glyph_position[i].y_offset;
@@ -3456,7 +3457,7 @@ static bool CollectGlyphsFromFont(TTF_Font *font, const char *text, size_t lengt
         pos->index = idx;
         pos->glyph = glyph;
         pos->offset = offset;
-        pos->x_advance = glyph->advance;
+        pos->x_advance = glyph->advance + font->char_spacing;
         pos->y_advance = 0;
         pos->x_offset = 0;
         pos->y_offset = 0;
@@ -3625,7 +3626,7 @@ static bool CollectGlyphs(TTF_Font *font, const char *text, size_t length, TTF_D
             if (!Find_GlyphByIndex(font, pos->index, 0, 0, 0, 0, 0, 0, &pos->glyph, NULL)) {
                 return SDL_SetError("Couldn't find glyph %u in font", pos->index);
             }
-            pos->x_advance = pos->glyph->advance;
+            pos->x_advance = pos->glyph->advance + font->char_spacing;
             pos->y_advance = 0;
             pos->x_offset = 0;
             pos->y_offset = 0;
@@ -5999,6 +6000,31 @@ TTF_Direction TTF_GetFontDirection(TTF_Font *font)
     return font->direction;
 }
 
+bool TTF_SetFontCharSpacing(TTF_Font *font, int spacing)
+{
+    TTF_CHECK_FONT(font, false);
+
+    ///* Convert integer pixels to FP 26.6 */
+    spacing = F26Dot6(spacing);
+
+    if (spacing == font->char_spacing) {
+        return true;
+    }
+
+    font->char_spacing = spacing;
+    Flush_Cache(font);
+    UpdateFontText(font, NULL);
+    return true;
+}
+
+int TTF_GetFontCharSpacing(TTF_Font *font)
+{
+    TTF_CHECK_FONT(font, 0);
+
+    /* Convert FP 26.6 to integer pixels */
+    return FT_FLOOR(font->char_spacing);
+}
+
 Uint32 TTF_StringToTag(const char *string)
 {
     Uint8 bytes[4] = { 0, 0, 0, 0 };

src/SDL_ttf.sym

@@ -117,5 +117,7 @@ SDL3_ttf_0.0.0 {
     TTF_UpdateText;
     TTF_Version;
     TTF_WasInit;
+    TTF_SetFontCharSpacing;
+    TTF_GetFontCharSpacing;
   local: *;
 };