web: reduce GlyphCache lock contention with FontSize handle

Add GlyphCache::FontSize, a lock-free handle that resolves a font size
once and provides glyph/kern/textWidth/cellHeight lookups without
re-acquiring the mutex. Update TileGenerator rendering loops (pin labels,
heatmap text, debug graphics) to resolve the font once per context.

Also check stbtt_InitFont return value and use unique_ptr for font_info_.

Signed-off-by: Matt Liberty <mliberty@precisioninno.com>

Author: maliberty

src/web/src/font_atlas.h

@@ -11,6 +11,11 @@
 
 namespace web {
 
+inline GlyphCache::FontSize fontAtlasGetFont(int height_px)
+{
+  return glyphCache().getFont(height_px);
+}
+
 inline int fontAtlasTextWidth(std::string_view text, int height_px)
 {
   return glyphCache().textWidth(text, height_px);

src/web/src/glyph_cache.cpp

@@ -6,7 +6,9 @@
 #include <algorithm>
 #include <cmath>
 #include <cstddef>
+#include <memory>
 #include <mutex>
+#include <stdexcept>
 #include <string_view>
 #include <vector>
 
@@ -22,15 +24,14 @@ constexpr int kNumGlyphs = kLastChar - kFirstChar + 1;
 }  // namespace
 
 GlyphCache::GlyphCache(const unsigned char* ttf_data, unsigned int /*ttf_size*/)
+    : font_info_(std::make_unique<stbtt_fontinfo>())
 {
-  font_info_ = new stbtt_fontinfo;
-  stbtt_InitFont(font_info_, ttf_data, 0);
+  if (!stbtt_InitFont(font_info_.get(), ttf_data, 0)) {
+    throw std::runtime_error("Failed to initialize font from TTF data");
+  }
 }
 
-GlyphCache::~GlyphCache()
-{
-  delete font_info_;
-}
+GlyphCache::~GlyphCache() = default;
 
 const GlyphCache::SizeSlot& GlyphCache::getSlot(int font_height) const
 {
@@ -41,10 +42,10 @@ const GlyphCache::SizeSlot& GlyphCache::getSlot(int font_height) const
   }
 
   SizeSlot& slot = cache_[font_height];
-  slot.scale = stbtt_ScaleForPixelHeight(font_info_, font_height);
+  slot.scale = stbtt_ScaleForPixelHeight(font_info_.get(), font_height);
 
   int ascent, descent, line_gap;
-  stbtt_GetFontVMetrics(font_info_, &ascent, &descent, &line_gap);
+  stbtt_GetFontVMetrics(font_info_.get(), &ascent, &descent, &line_gap);
   slot.ascent = static_cast<int>(std::round(ascent * slot.scale));
   const int desc_px = static_cast<int>(std::round(descent * slot.scale));
   slot.cell_height = slot.ascent - desc_px;
@@ -67,11 +68,11 @@ const GlyphCache::SizeSlot& GlyphCache::getSlot(int font_height) const
     auto& t = temps[i];
 
     int advance_raw, lsb_raw;
-    stbtt_GetCodepointHMetrics(font_info_, cp, &advance_raw, &lsb_raw);
+    stbtt_GetCodepointHMetrics(font_info_.get(), cp, &advance_raw, &lsb_raw);
     t.advance = static_cast<int>(std::round(advance_raw * slot.scale));
 
     unsigned char* bmp = stbtt_GetCodepointBitmap(
-        font_info_, 0, slot.scale, cp, &t.gw, &t.gh, &t.xoff, &t.yoff);
+        font_info_.get(), 0, slot.scale, cp, &t.gw, &t.gh, &t.xoff, &t.yoff);
     if (bmp && t.gw > 0 && t.gh > 0) {
       const size_t n = static_cast<size_t>(t.gw) * t.gh;
       t.bitmap.assign(bmp, bmp + n);
@@ -112,64 +113,95 @@ const GlyphCache::SizeSlot& GlyphCache::getSlot(int font_height) const
   return slot;
 }
 
-int GlyphCache::textWidth(std::string_view text, int font_height) const
+// --- FontSize (lock-free handle) -------------------------------------------
+
+GlyphCache::FontSize::FontSize(const SizeSlot& slot,
+                               const stbtt_fontinfo* font_info)
+    : slot_(slot), font_info_(font_info)
+{
+}
+
+GlyphCache::GlyphInfo GlyphCache::FontSize::glyph(char ch) const
+{
+  const int idx = static_cast<unsigned char>(ch) - kFirstChar;
+  if (idx < 0 || idx >= kNumGlyphs) {
+    return {.alpha = nullptr,
+            .bmp_width = 0,
+            .bmp_height = 0,
+            .x_offset = 0,
+            .y_offset = 0,
+            .advance = 0};
+  }
+  const auto& cg = slot_.glyphs[idx];
+  const unsigned char* alpha_ptr
+      = cg.bmp_width > 0 ? slot_.alpha.data() + cg.alpha_offset : nullptr;
+  return {.alpha = alpha_ptr,
+          .bmp_width = cg.bmp_width,
+          .bmp_height = cg.bmp_height,
+          .x_offset = cg.x_offset,
+          .y_offset = cg.y_offset,
+          .advance = cg.advance};
+}
+
+int GlyphCache::FontSize::kern(char ch1, char ch2) const
+{
+  const int raw = stbtt_GetCodepointKernAdvance(font_info_, ch1, ch2);
+  return static_cast<int>(std::round(raw * slot_.scale));
+}
+
+int GlyphCache::FontSize::textWidth(std::string_view text) const
 {
   if (text.empty()) {
     return 0;
   }
-  const auto& slot = getSlot(font_height);
   int width = 0;
   for (size_t i = 0; i < text.size(); ++i) {
     const int idx = static_cast<unsigned char>(text[i]) - kFirstChar;
     if (idx >= 0 && idx < kNumGlyphs) {
-      width += slot.glyphs[idx].advance;
+      width += slot_.glyphs[idx].advance;
     }
-    // Add kerning with next character.
     if (i + 1 < text.size()) {
-      width += kern(font_height, text[i], text[i + 1]);
+      width += kern(text[i], text[i + 1]);
     }
   }
   return width;
 }
 
+int GlyphCache::FontSize::cellHeight() const
+{
+  return slot_.cell_height;
+}
+
+// --- GlyphCache public API (convenience, locks per call) -------------------
+
+GlyphCache::FontSize GlyphCache::getFont(int font_height) const
+{
+  return FontSize(getSlot(font_height), font_info_.get());
+}
+
+int GlyphCache::textWidth(std::string_view text, int font_height) const
+{
+  return getFont(font_height).textWidth(text);
+}
+
 int GlyphCache::textHeight(int font_height) const
 {
-  return getSlot(font_height).cell_height;
+  return getFont(font_height).cellHeight();
 }
 
 int GlyphCache::cellHeight(int font_height) const
 {
-  return getSlot(font_height).cell_height;
+  return getFont(font_height).cellHeight();
 }
 
 GlyphCache::GlyphInfo GlyphCache::glyph(int font_height, char ch) const
 {
-  const int idx = static_cast<unsigned char>(ch) - kFirstChar;
-  const auto& slot = getSlot(font_height);
-  if (idx < 0 || idx >= kNumGlyphs) {
-    return {.alpha = nullptr,
-            .bmp_width = 0,
-            .bmp_height = 0,
-            .x_offset = 0,
-            .y_offset = 0,
-            .advance = 0};
-  }
-  const auto& cg = slot.glyphs[idx];
-  const unsigned char* alpha_ptr
-      = cg.bmp_width > 0 ? slot.alpha.data() + cg.alpha_offset : nullptr;
-  return {.alpha = alpha_ptr,
-          .bmp_width = cg.bmp_width,
-          .bmp_height = cg.bmp_height,
-          .x_offset = cg.x_offset,
-          .y_offset = cg.y_offset,
-          .advance = cg.advance};
+  return getFont(font_height).glyph(ch);
 }
 
 int GlyphCache::kern(int font_height, char ch1, char ch2) const
 {
-  const auto& slot = getSlot(font_height);
-  const int raw = stbtt_GetCodepointKernAdvance(font_info_, ch1, ch2);
-  return static_cast<int>(std::round(raw * slot.scale));
+  return getFont(font_height).kern(ch1, ch2);
 }
 
 const GlyphCache& glyphCache()

src/web/src/glyph_cache.h

@@ -9,6 +9,7 @@
 #pragma once
 
 #include <map>
+#include <memory>
 #include <mutex>
 #include <string_view>
 #include <vector>
@@ -21,17 +22,8 @@ struct Color;
 
 class GlyphCache
 {
- public:
-  // Initialize from raw TTF data (must remain valid for the cache lifetime).
-  GlyphCache(const unsigned char* ttf_data, unsigned int ttf_size);
-  ~GlyphCache();
-
-  // Total pixel width of a rendered string (includes kerning).
-  int textWidth(std::string_view text, int font_height) const;
-  // Line height in pixels.
-  int textHeight(int font_height) const;
-
   // Per-glyph rendering info.
+ public:
   struct GlyphInfo
   {
     const unsigned char* alpha;  // bitmap, bmp_width * bmp_height bytes
@@ -42,15 +34,6 @@ class GlyphCache
     int advance;                 // horizontal advance in pixels
   };
 
-  // Cell height (line height, same for all glyphs at a given size).
-  int cellHeight(int font_height) const;
-
-  // Look up a glyph.  Returns {nullptr,...} for space / unknown.
-  GlyphInfo glyph(int font_height, char ch) const;
-
-  // Kerning adjustment between two characters (in pixels).
-  int kern(int font_height, char ch1, char ch2) const;
-
  private:
   struct CachedGlyph
   {
@@ -71,9 +54,42 @@ class GlyphCache
     std::vector<unsigned char> alpha;  // packed glyph bitmaps
   };
 
+ public:
+  // Lock-free handle to a resolved font size.  Retrieve via getFont()
+  // and use for batch glyph/text operations without per-call locking.
+  class FontSize
+  {
+   public:
+    GlyphInfo glyph(char ch) const;
+    int kern(char ch1, char ch2) const;
+    int textWidth(std::string_view text) const;
+    int cellHeight() const;
+
+   private:
+    friend class GlyphCache;
+    FontSize(const SizeSlot& slot, const stbtt_fontinfo* font_info);
+    const SizeSlot& slot_;
+    const stbtt_fontinfo* font_info_;
+  };
+
+  // Initialize from raw TTF data (must remain valid for the cache lifetime).
+  GlyphCache(const unsigned char* ttf_data, unsigned int ttf_size);
+  ~GlyphCache();
+
+  // Acquire a FontSize handle (locks once, then all lookups are lock-free).
+  FontSize getFont(int font_height) const;
+
+  // Convenience methods — each locks internally per call.
+  int textWidth(std::string_view text, int font_height) const;
+  int textHeight(int font_height) const;
+  int cellHeight(int font_height) const;
+  GlyphInfo glyph(int font_height, char ch) const;
+  int kern(int font_height, char ch1, char ch2) const;
+
+ private:
   const SizeSlot& getSlot(int font_height) const;
 
-  stbtt_fontinfo* font_info_;
+  std::unique_ptr<stbtt_fontinfo> font_info_;
   mutable std::mutex mutex_;
   mutable std::map<int, SizeSlot> cache_;
 };