Cleanup: organize blf_font.c functions using doxy-sections

Functions in this file were scattered and not well organized.

1 files changed, 346 insertions, 283 deletions

diff --git a/source/blender/blenfont/intern/blf_font.c b/source/blender/blenfont/intern/blf_font.c
index 436c4712e25..47fa3544474 100644
--- a/source/blender/blenfont/intern/blf_font.c
+++ b/source/blender/blenfont/intern/blf_font.c
@@ -72,6 +72,38 @@ static SpinLock ft_lib_mutex;
 static SpinLock blf_glyph_cache_mutex;
 
 /* -------------------------------------------------------------------- */
+/** \name FreeType Utilities (Internal)
+ * \{ */
+
+/**
+ * Convert a FreeType 26.6 value representing an unscaled design size to pixels.
+ * This is an exact copy of the scaling done inside FT_Get_Kerning when called
+ * with #FT_KERNING_DEFAULT, including arbitrary resizing for small fonts.
+ */
+static int blf_unscaled_F26Dot6_to_pixels(FontBLF *font, FT_Pos value)
+{
+  /* Scale value by font size using integer-optimized multiplication. */
+  FT_Long scaled = FT_MulFix(value, font->face->size->metrics.x_scale);
+
+  /* FreeType states that this '25' has been determined heuristically. */
+  if (font->face->size->metrics.x_ppem < 25) {
+    scaled = FT_MulDiv(scaled, font->face->size->metrics.x_ppem, 25);
+  }
+
+  /* Copies of internal FreeType macros needed here. */
+#define FT_PIX_FLOOR(x) ((x) & ~63)
+#define FT_PIX_ROUND(x) FT_PIX_FLOOR((x) + 32)
+
+  /* Round to even 64ths, then divide by 64. */
+  return (int)FT_PIX_ROUND(scaled) >> 6;
+
+#undef FT_PIX_FLOOR
+#undef FT_PIX_ROUND
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
 /** \name Glyph Batching
  * \{ */
 
@@ -257,56 +289,8 @@ static void blf_batch_draw_end(void)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-
-int blf_font_init(void)
-{
-  memset(&g_batch, 0, sizeof(g_batch));
-  BLI_spin_init(&ft_lib_mutex);
-  BLI_spin_init(&blf_glyph_cache_mutex);
-  return FT_Init_FreeType(&ft_lib);
-}
-
-void blf_font_exit(void)
-{
-  FT_Done_FreeType(ft_lib);
-  BLI_spin_end(&ft_lib_mutex);
-  BLI_spin_end(&blf_glyph_cache_mutex);
-  blf_batch_draw_exit();
-}
-
-void blf_font_size(FontBLF *font, unsigned int size, unsigned int dpi)
-{
-  GlyphCacheBLF *gc;
-  FT_Error err;
-
-  blf_glyph_cache_acquire(font);
-
-  gc = blf_glyph_cache_find(font, size, dpi);
-  if (gc) {
-    /* Optimization: do not call FT_Set_Char_Size if size did not change. */
-    if (font->size == size && font->dpi == dpi) {
-      blf_glyph_cache_release(font);
-      return;
-    }
-  }
-
-  err = FT_Set_Char_Size(font->face, 0, ((FT_F26Dot6)(size)) * 64, dpi, dpi);
-  if (err) {
-    /* FIXME: here we can go through the fixed size and choice a close one */
-    printf("The current font don't support the size, %u and dpi, %u\n", size, dpi);
-
-    blf_glyph_cache_release(font);
-    return;
-  }
-
-  font->size = size;
-  font->dpi = dpi;
-
-  if (!gc) {
-    blf_glyph_cache_new(font);
-  }
-  blf_glyph_cache_release(font);
-}
+/** \name Glyph Stepping Utilities (Internal)
+ * \{ */
 
 /* Fast path for runs of ASCII characters. Given that common UTF-8
  * input will consist of an overwhelming majority of ASCII
@@ -337,31 +321,6 @@ BLI_INLINE GlyphBLF *blf_utf8_next_fast(
   return g;
 }
 
-/* Convert a FreeType 26.6 value representing an unscaled design size to pixels.
- * This is an exact copy of the scaling done inside FT_Get_Kerning when called
- * with FT_KERNING_DEFAULT, including arbitrary resizing for small fonts.
- */
-static int blf_unscaled_F26Dot6_to_pixels(FontBLF *font, FT_Pos value)
-{
-  /* Scale value by font size using integer-optimized multiplication. */
-  FT_Long scaled = FT_MulFix(value, font->face->size->metrics.x_scale);
-
-  /* FreeType states that this '25' has been determined heuristically. */
-  if (font->face->size->metrics.x_ppem < 25) {
-    scaled = FT_MulDiv(scaled, font->face->size->metrics.x_ppem, 25);
-  }
-
-  /* Copies of internal FreeType macros needed here. */
-#define FT_PIX_FLOOR(x) ((x) & ~63)
-#define FT_PIX_ROUND(x) FT_PIX_FLOOR((x) + 32)
-
-  /* Round to even 64ths, then divide by 64. */
-  return (int)FT_PIX_ROUND(scaled) >> 6;
-
-#undef FT_PIX_FLOOR
-#undef FT_PIX_ROUND
-}
-
 BLI_INLINE void blf_kerning_step_fast(FontBLF *font,
                                       const GlyphBLF *g_prev,
                                       const GlyphBLF *g,
@@ -395,6 +354,12 @@ BLI_INLINE void blf_kerning_step_fast(FontBLF *font,
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Drawing: GPU
+ * \{ */
+
 static void blf_font_draw_ex(FontBLF *font,
                              GlyphCacheBLF *gc,
                              const char *str,
@@ -535,6 +500,12 @@ int blf_font_draw_mono(FontBLF *font, const char *str, size_t len, int cwidth)
   return columns;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Drawgin: Buffer
+ * \{ */
+
 /* Sanity checks are done by BLF_draw_buffer() */
 static void blf_font_draw_buffer_ex(FontBLF *font,
                                     GlyphCacheBLF *gc,
@@ -680,6 +651,16 @@ void blf_font_draw_buffer(FontBLF *font, const char *str, size_t len, struct Res
   blf_glyph_cache_release(font);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Evaluation: Width to Sting Length
+ *
+ * Use to implement exported functions:
+ * - #BLF_width_to_strlen
+ * - #BLF_width_to_rstrlen
+ * \{ */
+
 static bool blf_font_width_to_strlen_glyph_process(FontBLF *font,
                                                    const uint c_prev,
                                                    const uint c,
@@ -773,6 +754,12 @@ size_t blf_font_width_to_rstrlen(
   return i;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Text Evaluation: Glyph Bound Box with Callback
+ * \{ */
+
 static void blf_font_boundbox_ex(FontBLF *font,
                                  GlyphCacheBLF *gc,
                                  const char *str,
@@ -847,8 +834,165 @@ void blf_font_boundbox(
   blf_glyph_cache_release(font);
 }
 
+void blf_font_width_and_height(FontBLF *font,
+                               const char *str,
+                               size_t len,
+                               float *r_width,
+                               float *r_height,
+                               struct ResultBLF *r_info)
+{
+  float xa, ya;
+  rctf box;
+
+  if (font->flags & BLF_ASPECT) {
+    xa = font->aspect[0];
+    ya = font->aspect[1];
+  }
+  else {
+    xa = 1.0f;
+    ya = 1.0f;
+  }
+
+  if (font->flags & BLF_WORD_WRAP) {
+    blf_font_boundbox__wrap(font, str, len, &box, r_info);
+  }
+  else {
+    blf_font_boundbox(font, str, len, &box, r_info);
+  }
+  *r_width = (BLI_rctf_size_x(&box) * xa);
+  *r_height = (BLI_rctf_size_y(&box) * ya);
+}
+
+float blf_font_width(FontBLF *font, const char *str, size_t len, struct ResultBLF *r_info)
+{
+  float xa;
+  rctf box;
+
+  if (font->flags & BLF_ASPECT) {
+    xa = font->aspect[0];
+  }
+  else {
+    xa = 1.0f;
+  }
+
+  if (font->flags & BLF_WORD_WRAP) {
+    blf_font_boundbox__wrap(font, str, len, &box, r_info);
+  }
+  else {
+    blf_font_boundbox(font, str, len, &box, r_info);
+  }
+  return BLI_rctf_size_x(&box) * xa;
+}
+
+float blf_font_height(FontBLF *font, const char *str, size_t len, struct ResultBLF *r_info)
+{
+  float ya;
+  rctf box;
+
+  if (font->flags & BLF_ASPECT) {
+    ya = font->aspect[1];
+  }
+  else {
+    ya = 1.0f;
+  }
+
+  if (font->flags & BLF_WORD_WRAP) {
+    blf_font_boundbox__wrap(font, str, len, &box, r_info);
+  }
+  else {
+    blf_font_boundbox(font, str, len, &box, r_info);
+  }
+  return BLI_rctf_size_y(&box) * ya;
+}
+
+float blf_font_fixed_width(FontBLF *font)
+{
+  const unsigned int c = ' ';
+
+  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
+  GlyphBLF *g = blf_glyph_search(gc, c);
+  if (!g) {
+    g = blf_glyph_add(font, gc, FT_Get_Char_Index(font->face, c), c);
+
+    /* if we don't find the glyph. */
+    if (!g) {
+      blf_glyph_cache_release(font);
+      return 0.0f;
+    }
+  }
+
+  blf_glyph_cache_release(font);
+  return g->advance;
+}
+
+static void blf_font_boundbox_foreach_glyph_ex(FontBLF *font,
+                                               GlyphCacheBLF *gc,
+                                               const char *str,
+                                               size_t len,
+                                               BLF_GlyphBoundsFn user_fn,
+                                               void *user_data,
+                                               struct ResultBLF *r_info,
+                                               int pen_y)
+{
+  unsigned int c, c_prev = BLI_UTF8_ERR;
+  GlyphBLF *g, *g_prev = NULL;
+  int pen_x = 0;
+  size_t i = 0, i_curr;
+  rcti gbox;
+
+  if (len == 0) {
+    /* early output. */
+    return;
+  }
+
+  while ((i < len) && str[i]) {
+    i_curr = i;
+    g = blf_utf8_next_fast(font, gc, str, &i, &c);
+
+    if (UNLIKELY(c == BLI_UTF8_ERR)) {
+      break;
+    }
+    if (UNLIKELY(g == NULL)) {
+      continue;
+    }
+    blf_kerning_step_fast(font, g_prev, g, c_prev, c, &pen_x);
+
+    gbox.xmin = pen_x;
+    gbox.xmax = gbox.xmin + MIN2(g->advance_i, g->dims[0]);
+    gbox.ymin = pen_y;
+    gbox.ymax = gbox.ymin - g->dims[1];
+
+    pen_x += g->advance_i;
+
+    if (user_fn(str, i_curr, &gbox, g->advance_i, &g->box, g->pos, user_data) == false) {
+      break;
+    }
+
+    g_prev = g;
+    c_prev = c;
+  }
+
+  if (r_info) {
+    r_info->lines = 1;
+    r_info->width = pen_x;
+  }
+}
+void blf_font_boundbox_foreach_glyph(FontBLF *font,
+                                     const char *str,
+                                     size_t len,
+                                     BLF_GlyphBoundsFn user_fn,
+                                     void *user_data,
+                                     struct ResultBLF *r_info)
+{
+  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
+  blf_font_boundbox_foreach_glyph_ex(font, gc, str, len, user_fn, user_data, r_info, 0);
+  blf_glyph_cache_release(font);
+}
+
+/** \} */
+
 /* -------------------------------------------------------------------- */
-/** \name Word-Wrap Support
+/** \name Text Evaluation: Word-Wrap with Callback
  * \{ */
 
 /**
@@ -1018,216 +1162,120 @@ void blf_font_draw_buffer__wrap(FontBLF *font,
 
 /** \} */
 
-void blf_font_width_and_height(FontBLF *font,
-                               const char *str,
-                               size_t len,
-                               float *r_width,
-                               float *r_height,
-                               struct ResultBLF *r_info)
+/* -------------------------------------------------------------------- */
+/** \name Text Evaluation: Count Missing Characters
+ * \{ */
+
+int blf_font_count_missing_chars(FontBLF *font,
+                                 const char *str,
+                                 const size_t len,
+                                 int *r_tot_chars)
 {
-  float xa, ya;
-  rctf box;
+  int missing = 0;
+  size_t i = 0;
 
-  if (font->flags & BLF_ASPECT) {
-    xa = font->aspect[0];
-    ya = font->aspect[1];
-  }
-  else {
-    xa = 1.0f;
-    ya = 1.0f;
-  }
+  *r_tot_chars = 0;
+  while (i < len) {
+    unsigned int c;
 
-  if (font->flags & BLF_WORD_WRAP) {
-    blf_font_boundbox__wrap(font, str, len, &box, r_info);
-  }
-  else {
-    blf_font_boundbox(font, str, len, &box, r_info);
+    if ((c = str[i]) < GLYPH_ASCII_TABLE_SIZE) {
+      i++;
+    }
+    else if ((c = BLI_str_utf8_as_unicode_step(str, &i)) != BLI_UTF8_ERR) {
+      if (FT_Get_Char_Index((font)->face, c) == 0) {
+        missing++;
+      }
+    }
+    (*r_tot_chars)++;
   }
-  *r_width = (BLI_rctf_size_x(&box) * xa);
-  *r_height = (BLI_rctf_size_y(&box) * ya);
+  return missing;
 }
 
-float blf_font_width(FontBLF *font, const char *str, size_t len, struct ResultBLF *r_info)
-{
-  float xa;
-  rctf box;
-
-  if (font->flags & BLF_ASPECT) {
-    xa = font->aspect[0];
-  }
-  else {
-    xa = 1.0f;
-  }
+/** \} */
 
-  if (font->flags & BLF_WORD_WRAP) {
-    blf_font_boundbox__wrap(font, str, len, &box, r_info);
-  }
-  else {
-    blf_font_boundbox(font, str, len, &box, r_info);
-  }
-  return BLI_rctf_size_x(&box) * xa;
-}
+/* -------------------------------------------------------------------- */
+/** \name Font Query: Attributes
+ * \{ */
 
-float blf_font_height(FontBLF *font, const char *str, size_t len, struct ResultBLF *r_info)
+int blf_font_height_max(FontBLF *font)
 {
-  float ya;
-  rctf box;
+  int height_max;
 
-  if (font->flags & BLF_ASPECT) {
-    ya = font->aspect[1];
-  }
-  else {
-    ya = 1.0f;
-  }
+  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
+  height_max = gc->glyph_height_max;
 
-  if (font->flags & BLF_WORD_WRAP) {
-    blf_font_boundbox__wrap(font, str, len, &box, r_info);
-  }
-  else {
-    blf_font_boundbox(font, str, len, &box, r_info);
-  }
-  return BLI_rctf_size_y(&box) * ya;
+  blf_glyph_cache_release(font);
+  return height_max;
 }
 
-float blf_font_fixed_width(FontBLF *font)
+int blf_font_width_max(FontBLF *font)
 {
-  const unsigned int c = ' ';
+  int width_max;
 
   GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
-  GlyphBLF *g = blf_glyph_search(gc, c);
-  if (!g) {
-    g = blf_glyph_add(font, gc, FT_Get_Char_Index(font->face, c), c);
-
-    /* if we don't find the glyph. */
-    if (!g) {
-      blf_glyph_cache_release(font);
-      return 0.0f;
-    }
-  }
+  width_max = gc->glyph_width_max;
 
   blf_glyph_cache_release(font);
-  return g->advance;
+  return width_max;
 }
 
-/* -------------------------------------------------------------------- */
-/** \name Glyph Bound Box with Callback
- * \{ */
-
-static void blf_font_boundbox_foreach_glyph_ex(FontBLF *font,
-                                               GlyphCacheBLF *gc,
-                                               const char *str,
-                                               size_t len,
-                                               BLF_GlyphBoundsFn user_fn,
-                                               void *user_data,
-                                               struct ResultBLF *r_info,
-                                               int pen_y)
+float blf_font_descender(FontBLF *font)
 {
-  unsigned int c, c_prev = BLI_UTF8_ERR;
-  GlyphBLF *g, *g_prev = NULL;
-  int pen_x = 0;
-  size_t i = 0, i_curr;
-  rcti gbox;
-
-  if (len == 0) {
-    /* early output. */
-    return;
-  }
-
-  while ((i < len) && str[i]) {
-    i_curr = i;
-    g = blf_utf8_next_fast(font, gc, str, &i, &c);
-
-    if (UNLIKELY(c == BLI_UTF8_ERR)) {
-      break;
-    }
-    if (UNLIKELY(g == NULL)) {
-      continue;
-    }
-    blf_kerning_step_fast(font, g_prev, g, c_prev, c, &pen_x);
+  float descender;
 
-    gbox.xmin = pen_x;
-    gbox.xmax = gbox.xmin + MIN2(g->advance_i, g->dims[0]);
-    gbox.ymin = pen_y;
-    gbox.ymax = gbox.ymin - g->dims[1];
+  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
+  descender = gc->descender;
 
-    pen_x += g->advance_i;
+  blf_glyph_cache_release(font);
+  return descender;
+}
 
-    if (user_fn(str, i_curr, &gbox, g->advance_i, &g->box, g->pos, user_data) == false) {
-      break;
-    }
+float blf_font_ascender(FontBLF *font)
+{
+  float ascender;
 
-    g_prev = g;
-    c_prev = c;
-  }
+  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
+  ascender = gc->ascender;
 
-  if (r_info) {
-    r_info->lines = 1;
-    r_info->width = pen_x;
-  }
+  blf_glyph_cache_release(font);
+  return ascender;
 }
-void blf_font_boundbox_foreach_glyph(FontBLF *font,
-                                     const char *str,
-                                     size_t len,
-                                     BLF_GlyphBoundsFn user_fn,
-                                     void *user_data,
-                                     struct ResultBLF *r_info)
+
+char *blf_display_name(FontBLF *font)
 {
-  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
-  blf_font_boundbox_foreach_glyph_ex(font, gc, str, len, user_fn, user_data, r_info, 0);
-  blf_glyph_cache_release(font);
+  if (!font->face->family_name) {
+    return NULL;
+  }
+  return BLI_sprintfN("%s %s", font->face->family_name, font->face->style_name);
 }
 
 /** \} */
 
-int blf_font_count_missing_chars(FontBLF *font,
-                                 const char *str,
-                                 const size_t len,
-                                 int *r_tot_chars)
-{
-  int missing = 0;
-  size_t i = 0;
-
-  *r_tot_chars = 0;
-  while (i < len) {
-    unsigned int c;
+/* -------------------------------------------------------------------- */
+/** \name Font Subsystem Init/Exit
+ * \{ */
 
-    if ((c = str[i]) < GLYPH_ASCII_TABLE_SIZE) {
-      i++;
-    }
-    else if ((c = BLI_str_utf8_as_unicode_step(str, &i)) != BLI_UTF8_ERR) {
-      if (FT_Get_Char_Index((font)->face, c) == 0) {
-        missing++;
-      }
-    }
-    (*r_tot_chars)++;
-  }
-  return missing;
+int blf_font_init(void)
+{
+  memset(&g_batch, 0, sizeof(g_batch));
+  BLI_spin_init(&ft_lib_mutex);
+  BLI_spin_init(&blf_glyph_cache_mutex);
+  return FT_Init_FreeType(&ft_lib);
 }
 
-void blf_font_free(FontBLF *font)
+void blf_font_exit(void)
 {
-  BLI_spin_lock(&blf_glyph_cache_mutex);
-  GlyphCacheBLF *gc;
-
-  while ((gc = BLI_pophead(&font->cache))) {
-    blf_glyph_cache_free(gc);
-  }
-
-  if (font->kerning_cache) {
-    MEM_freeN(font->kerning_cache);
-  }
+  FT_Done_FreeType(ft_lib);
+  BLI_spin_end(&ft_lib_mutex);
+  BLI_spin_end(&blf_glyph_cache_mutex);
+  blf_batch_draw_exit();
+}
 
-  FT_Done_Face(font->face);
-  if (font->filename) {
-    MEM_freeN(font->filename);
-  }
-  if (font->name) {
-    MEM_freeN(font->name);
-  }
-  MEM_freeN(font);
+/** \} */
 
-  BLI_spin_unlock(&blf_glyph_cache_mutex);
-}
+/* -------------------------------------------------------------------- */
+/** \name Font New/Free
+ * \{ */
 
 static void blf_font_fill(FontBLF *font)
 {
@@ -1366,54 +1414,69 @@ FontBLF *blf_font_new_from_mem(const char *name, const unsigned char *mem, int m
   return font;
 }
 
-int blf_font_height_max(FontBLF *font)
+void blf_font_free(FontBLF *font)
 {
-  int height_max;
-
-  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
-  height_max = gc->glyph_height_max;
+  BLI_spin_lock(&blf_glyph_cache_mutex);
+  GlyphCacheBLF *gc;
 
-  blf_glyph_cache_release(font);
-  return height_max;
-}
+  while ((gc = BLI_pophead(&font->cache))) {
+    blf_glyph_cache_free(gc);
+  }
 
-int blf_font_width_max(FontBLF *font)
-{
-  int width_max;
+  if (font->kerning_cache) {
+    MEM_freeN(font->kerning_cache);
+  }
 
-  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
-  width_max = gc->glyph_width_max;
+  FT_Done_Face(font->face);
+  if (font->filename) {
+    MEM_freeN(font->filename);
+  }
+  if (font->name) {
+    MEM_freeN(font->name);
+  }
+  MEM_freeN(font);
 
-  blf_glyph_cache_release(font);
-  return width_max;
+  BLI_spin_unlock(&blf_glyph_cache_mutex);
 }
 
-float blf_font_descender(FontBLF *font)
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Font Configure
+ * \{ */
+
+void blf_font_size(FontBLF *font, unsigned int size, unsigned int dpi)
 {
-  float descender;
+  GlyphCacheBLF *gc;
+  FT_Error err;
 
-  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
-  descender = gc->descender;
+  blf_glyph_cache_acquire(font);
 
-  blf_glyph_cache_release(font);
-  return descender;
-}
+  gc = blf_glyph_cache_find(font, size, dpi);
+  if (gc) {
+    /* Optimization: do not call FT_Set_Char_Size if size did not change. */
+    if (font->size == size && font->dpi == dpi) {
+      blf_glyph_cache_release(font);
+      return;
+    }
+  }
 
-float blf_font_ascender(FontBLF *font)
-{
-  float ascender;
+  err = FT_Set_Char_Size(font->face, 0, ((FT_F26Dot6)(size)) * 64, dpi, dpi);
+  if (err) {
+    /* FIXME: here we can go through the fixed size and choice a close one */
+    printf("The current font don't support the size, %u and dpi, %u\n", size, dpi);
 
-  GlyphCacheBLF *gc = blf_glyph_cache_acquire(font);
-  ascender = gc->ascender;
+    blf_glyph_cache_release(font);
+    return;
+  }
 
-  blf_glyph_cache_release(font);
-  return ascender;
-}
+  font->size = size;
+  font->dpi = dpi;
 
-char *blf_display_name(FontBLF *font)
-{
-  if (!font->face->family_name) {
-    return NULL;
+  if (!gc) {
+    blf_glyph_cache_new(font);
   }
-  return BLI_sprintfN("%s %s", font->face->family_name, font->face->style_name);
+  blf_glyph_cache_release(font);
 }
+
+/** \} */