From b1de87b7f1ebe62fc9325679489718494ec1d3a2 Mon Sep 17 00:00:00 2001
From: Behdad Esfahbod <behdad@behdad.org>
Date: Thu, 29 Dec 2022 10:34:47 -0700
Subject: [PATCH] [cairo] Document get_glyphs() arguments as inout

---
 src/hb-cairo.cc      | 39 +++++++++++++++++++++++++++++++++------
 util/helper-cairo.hh |  2 ++
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/src/hb-cairo.cc b/src/hb-cairo.cc
index 9e52fd215..71bd05153 100644
--- a/src/hb-cairo.cc
+++ b/src/hb-cairo.cc
@@ -763,16 +763,39 @@ hb_cairo_font_face_get_scale_factor (cairo_font_face_t *font_face)
  * @utf8: (nullable): the text that was shaped in @buffer
  * @utf8_len: the length of @utf8 in bytes
  * @glyphs: (out): return location for an array of #cairo_glyph_t
- * @num_glyphs: (out): return location for the length of @glyphs
+ * @num_glyphs: (inout): return location for the length of @glyphs
  * @clusters: (out) (nullable): return location for an array of cluster positions
- * @num_clusters: (out) (nullable): return location for the length of @clusters
+ * @num_clusters: (inout) (nullable): return location for the length of @clusters
  * @cluster_flags: (out) (nullable): return location for cluster flags
  *
  * Extracts information from @buffer in a form that can be
  * passed to cairo_show_text_glyphs() or cairo_show_glyphs().
- * This API is modeled after cairo_scaled_font_text_to_glyphs().
+ * This API is modeled after cairo_scaled_font_text_to_glyphs() and
+ * cairo_user_scaled_font_text_to_glyphs_func_t.
  *
- * If cluster information is requested, @utf8 must be provided.
+ * The @num_glyphs argument should be preset to the number of glyph entries available
+ * in the @glyphs buffer. If the @glyphs buffer is %NULL, the value of
+ * @num_glyphs must be zero.  If the provided glyph array is too short for
+ * the conversion (or for convenience), a new glyph array may be allocated
+ * using cairo_glyph_allocate() and placed in @glyphs.  Upon return,
+ * @num_glyphs should contain the number of generated glyphs.  If the value
+ * @glyphs points at has changed after the call, the caller will free the
+ * allocated glyph array using cairo_glyph_free().  The caller will also free
+ * the original value of @glyphs, so this function shouldn't do so.
+ *
+ * If @clusters is not %NULL, then @num_clusters and @cluster_flags
+ * should not be either, and @utf8 must be provided, and cluster
+ * mapping will be computed. The semantics of how
+ * cluster array allocation works is similar to the glyph array.  That is,
+ * if @clusters initially points to a non-%NULL value, that array may be used
+ * as a cluster buffer, and @num_clusters points to the number of cluster
+ * entries available there.  If the provided cluster array is too short for
+ * the conversion (or for convenience), a new cluster array may be allocated
+ * using cairo_text_cluster_allocate() and placed in @clusters.  In this case,
+ * the original value of @clusters will still be freed by the caller.  Upon
+ * return, @num_clusters will contain the number of generated clusters.
+ * If the value @clusters points at has changed after the call, the caller
+ * will free the allocated cluster array using cairo_text_cluster_free().
  *
  * See hb_cairo_font_face_set_scale_factor() for the details of
  * the @scale_factor argument.
@@ -801,18 +824,22 @@ hb_cairo_glyphs_from_buffer (hb_buffer_t *buffer,
   if (utf8 && utf8_len < 0)
     utf8_len = strlen (utf8);
 
+  unsigned orig_num_glyphs = *num_glyphs;
   *num_glyphs = hb_buffer_get_length (buffer);
   hb_glyph_info_t *hb_glyph = hb_buffer_get_glyph_infos (buffer, nullptr);
   hb_glyph_position_t *hb_position = hb_buffer_get_glyph_positions (buffer, nullptr);
-  *glyphs = cairo_glyph_allocate (*num_glyphs + 1);
+  if (orig_num_glyphs < *num_glyphs + 1)
+    *glyphs = cairo_glyph_allocate (*num_glyphs + 1);
 
   if (clusters)
   {
+    unsigned orig_num_clusters = *num_clusters;
     *num_clusters = *num_glyphs ? 1 : 0;
     for (unsigned int i = 1; i < *num_glyphs; i++)
       if (hb_glyph[i].cluster != hb_glyph[i-1].cluster)
 	(*num_clusters)++;
-    *clusters = cairo_text_cluster_allocate (*num_clusters);
+    if (orig_num_clusters < *num_clusters)
+      *clusters = cairo_text_cluster_allocate (*num_clusters);
   }
 
   if ((*num_glyphs && !*glyphs) ||
diff --git a/util/helper-cairo.hh b/util/helper-cairo.hh
index 604271949..e47fefa27 100644
--- a/util/helper-cairo.hh
+++ b/util/helper-cairo.hh
@@ -604,6 +604,8 @@ helper_cairo_line_from_buffer (helper_cairo_line_t *l,
 			       int                  scale_bits,
 			       hb_bool_t            utf8_clusters)
 {
+  memset (l, 0, sizeof (*l));
+
   l->utf8 = text ? g_strndup (text, text_len) : nullptr;
   l->utf8_len = text ? text_len : 0;