Alias cairo_user_scaled_font_text_to_glyphs_func_t
cairo_user_scaled_font_text_to_glyphs_func_t
is the type of function which
is called to convert input text to an array of glyphs. This is used by the
cairo_show_text
() operation.
Using this callback the user-font has full control on glyphs and their positions. That means, it allows for features like ligatures and kerning, as well as complex shaping required for scripts like Arabic and Indic.
The num_glyphs argument is preset to the number of glyph entries available
in the glyphs buffer. If the glyphs buffer is NULL, the value of
num_glyphs will 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 callback should populate the glyph indices and positions (in font space)
assuming that the text is to be shown at the origin.
If clusters is not NULL, num_clusters and cluster_flags are also
non-NULL, and cluster mapping should 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. Upon return,
num_clusters should 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
().
The callback is optional. If num_glyphs is negative upon
the callback returning or if the return value
is CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback
is tried. See cairo_user_scaled_font_unicode_to_glyph_func_t
.
Declaration
alias cairo_user_scaled_font_text_to_glyphs_func_t = extern(C) cairo_status_t function(cairo_scaled_font_t*, const(char*), int, cairo_glyph_t**, int*, cairo_text_cluster_t**, int*, cairo_text_cluster_flags_t*);
Note
While cairo does not impose any limitation on glyph indices, some applications may assume that a glyph index fits in a 16-bit unsigned integer. As such, it is advised that user-fonts keep their glyphs in the 0 to 65535 range. Furthermore, some applications may assume that glyph 0 is a special glyph-not-found glyph. User-fonts are advised to use glyph 0 for such purposes and do not use that glyph value for other purposes.
Parameters
Name | Description |
---|---|
scaled_font | the scaled-font being created |
utf8 | a string of text encoded in UTF-8 |
utf8_len | length of @utf8 in bytes |
glyphs | pointer to array of glyphs to fill, in font space |
num_glyphs | pointer to number of glyphs |
clusters | pointer to array of cluster mapping information to fill, or %NULL |
num_clusters | pointer to number of clusters |
cluster_flags | pointer to location to store cluster flags corresponding to the output @clusters |
Returns
CAIRO_STATUS_SUCCESS upon success, CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, or CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
Since
1.8
Authors
Johannes Pfau | cairoD |
cairo team | cairo |
Copyright
License
cairoD wrapper/bindings | Boost License 1.0 |
cairo | LGPL 2.1 / MPL 1.1 |