[cairo] Document get_glyphs() arguments as inout

This commit is contained in:
Behdad Esfahbod 2022-12-29 10:34:47 -07:00
parent 3be9fa07f6
commit b1de87b7f1
2 changed files with 35 additions and 6 deletions

View File

@ -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,17 +824,21 @@ 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);
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)++;
if (orig_num_clusters < *num_clusters)
*clusters = cairo_text_cluster_allocate (*num_clusters);
}

View File

@ -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;