User Fonts: Cairo: A Vector Graphics Library

+ + +

User Fonts

User Fonts — Font support with font data provided by the user

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+cairo_status_t +	+(*cairo_user_scaled_font_init_func_t) () +
+cairo_status_t +	+(*cairo_user_scaled_font_render_glyph_func_t) () +
+cairo_status_t +	+(*cairo_user_scaled_font_text_to_glyphs_func_t) () +
+cairo_status_t +	+(*cairo_user_scaled_font_unicode_to_glyph_func_t) () +
+cairo_font_face_t * +	+cairo_user_font_face_create () +
+void +	+cairo_user_font_face_set_init_func () +
+cairo_user_scaled_font_init_func_t +	+cairo_user_font_face_get_init_func () +
+void +	+cairo_user_font_face_set_render_glyph_func () +
+cairo_user_scaled_font_render_glyph_func_t +	+cairo_user_font_face_get_render_glyph_func () +
+void +	+cairo_user_font_face_set_unicode_to_glyph_func () +
+cairo_user_scaled_font_unicode_to_glyph_func_t +	+cairo_user_font_face_get_unicode_to_glyph_func () +
+void +	+cairo_user_font_face_set_text_to_glyphs_func () +
+cairo_user_scaled_font_text_to_glyphs_func_t +	+cairo_user_font_face_get_text_to_glyphs_func () +

Types and Values

++++ + + + + +

#define

CAIRO_HAS_USER_FONT

Description

The user-font feature allows the cairo user to provide drawings for glyphs +in a font. This is most useful in implementing fonts in non-standard +formats, like SVG fonts and Flash fonts, but can also be used by games and +other application to draw "funky" fonts.

Functions

cairo_user_scaled_font_init_func_t ()

cairo_status_t
+(*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t *scaled_font,
+                                       cairo_t *cr,
+                                       cairo_font_extents_t *extents);

cairo_user_scaled_font_init_func_t is the type of function which is +called when a scaled-font needs to be created for a user font-face.

The cairo context cr + is not used by the caller, but is prepared in font +space, similar to what the cairo contexts passed to the render_glyph +method will look like. The callback can use this context for extents +computation for example. After the callback is called, cr + is checked +for any error status.

The extents + argument is where the user font sets the font extents for +scaled_font +. It is in font space, which means that for most cases its +ascent and descent members should add to 1.0. extents + is preset to +hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for +descent and max_y_advance members.

The callback is optional. If not set, default font extents as described +in the previous paragraph will be used.

Note that scaled_font + is not fully initialized at this +point and trying to use it for text operations in the callback will result +in deadlock.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

scaled_font	the scaled-font being created
cr	a cairo context, in font space
extents	font extents to fill in, in font space

Returns

CAIRO_STATUS_SUCCESS upon success, or an error status on error.

Since: 1.8

cairo_user_scaled_font_render_glyph_func_t ()

cairo_status_t
+(*cairo_user_scaled_font_render_glyph_func_t)
+                               (cairo_scaled_font_t *scaled_font,
+                                unsigned long  glyph,
+                                cairo_t *cr,
+                                cairo_text_extents_t *extents);

cairo_user_scaled_font_render_glyph_func_t is the type of function which +is called when a user scaled-font needs to render a glyph.

The callback is mandatory, and expected to draw the glyph with code glyph + to +the cairo context cr +. cr + is prepared such that the glyph drawing is done in +font space. That is, the matrix set on cr + is the scale matrix of scaled_font +, +The extents + argument is where the user font sets the font extents for +scaled_font +. However, if user prefers to draw in user space, they can +achieve that by changing the matrix on cr +. All cairo rendering operations +to cr + are permitted, however, the result is undefined if any source other +than the default source on cr + is used. That means, glyph bitmaps should +be rendered using cairo_mask() instead of cairo_paint().

Other non-default settings on cr + include a font size of 1.0 (given that +it is set up to be in font space), and font options corresponding to +scaled_font +.

The extents + argument is preset to have x_bearing, +width, and y_advance of zero, +y_bearing set to -font_extents.ascent, +height to font_extents.ascent+font_extents.descent, +and x_advance to font_extents.max_x_advance. +The only field user needs to set in majority of cases is +x_advance. +If the width field is zero upon the callback returning +(which is its preset value), the glyph extents are automatically computed +based on the drawings done to cr +. This is in most cases exactly what the +desired behavior is. However, if for any reason the callback sets the +extents, it must be ink extents, and include the extents of all drawing +done to cr + in the callback.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

scaled_font	user scaled-font
glyph	glyph code to render
cr	cairo context to draw to, in font space
extents	glyph extents to fill in, in font space

Returns

CAIRO_STATUS_SUCCESS upon success, or +CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.

Since: 1.8

cairo_user_scaled_font_text_to_glyphs_func_t ()

cairo_status_t
+(*cairo_user_scaled_font_text_to_glyphs_func_t)
+                               (cairo_scaled_font_t *scaled_font,
+                                const char *utf8,
+                                int utf8_len,
+                                cairo_glyph_t **glyphs,
+                                int *num_glyphs,
+                                cairo_text_cluster_t **clusters,
+                                int *num_clusters,
+                                cairo_text_cluster_flags_t *cluster_flags);

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 caller will also free +the original value of glyphs +, so the callback shouldn't do so. +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 +. In this case, +the original value of clusters + will still be freed by the caller. 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.

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

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

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

cairo_user_scaled_font_unicode_to_glyph_func_t ()

cairo_status_t
+(*cairo_user_scaled_font_unicode_to_glyph_func_t)
+                               (cairo_scaled_font_t *scaled_font,
+                                unsigned long  unicode,
+                                unsigned long *glyph_index);

cairo_user_scaled_font_unicode_to_glyph_func_t is the type of function which +is called to convert an input Unicode character to a single glyph. +This is used by the cairo_show_text() operation.

This callback is used to provide the same functionality as the +text_to_glyphs callback does (see cairo_user_scaled_font_text_to_glyphs_func_t) +but has much less control on the output, +in exchange for increased ease of use. The inherent assumption to using +this callback is that each character maps to one glyph, and that the +mapping is context independent. It also assumes that glyphs are positioned +according to their advance width. These mean no ligatures, kerning, or +complex scripts can be implemented using this callback.

The callback is optional, and only used if text_to_glyphs callback is not +set or fails to return glyphs. If this callback is not set or if it returns +CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, an identity mapping from Unicode +code-points to glyph indices is assumed.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

scaled_font	the scaled-font being created
unicode	input unicode character code-point
glyph_index	output glyph index

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

cairo_user_font_face_create ()

cairo_font_face_t *
+cairo_user_font_face_create (void);

Creates a new user font-face.

Use the setter functions to associate callbacks with the returned +user font. The only mandatory callback is render_glyph.

After the font-face is created, the user can attach arbitrary data +(the actual font data) to it using cairo_font_face_set_user_data() +and access it from the user-font callbacks by using +cairo_scaled_font_get_font_face() followed by +cairo_font_face_get_user_data().

Returns

a newly created cairo_font_face_t. Free with +cairo_font_face_destroy() when you are done using it.

Since: 1.8

cairo_user_font_face_set_init_func ()

void
+cairo_user_font_face_set_init_func (cairo_font_face_t *font_face,
+                                    cairo_user_scaled_font_init_func_t init_func);

Sets the scaled-font initialization function of a user-font. +See cairo_user_scaled_font_init_func_t for details of how the callback +works.

The font-face should not be immutable or a CAIRO_STATUS_USER_FONT_IMMUTABLE +error will occur. A user font-face is immutable as soon as a scaled-font +is created from it.

Parameters

+++++ + + + + + + + + + + + + +

font_face	A user font face
init_func	The init callback, or `NULL`

Since: 1.8

cairo_user_font_face_get_init_func ()

cairo_user_scaled_font_init_func_t
+cairo_user_font_face_get_init_func (cairo_font_face_t *font_face);

Gets the scaled-font initialization function of a user-font.

Parameters

+++++ + + + + + +

font_face

A user font face

Returns

The init callback of font_face +or NULL if none set or an error has occurred.

Since: 1.8

cairo_user_font_face_set_render_glyph_func ()

void
+cairo_user_font_face_set_render_glyph_func
+                               (cairo_font_face_t *font_face,
+                                cairo_user_scaled_font_render_glyph_func_t render_glyph_func);

Sets the glyph rendering function of a user-font. +See cairo_user_scaled_font_render_glyph_func_t for details of how the callback +works.

The font-face should not be immutable or a CAIRO_STATUS_USER_FONT_IMMUTABLE +error will occur. A user font-face is immutable as soon as a scaled-font +is created from it.

The render_glyph callback is the only mandatory callback of a user-font. +If the callback is NULL and a glyph is tried to be rendered using +font_face +, a CAIRO_STATUS_USER_FONT_ERROR will occur.

Parameters

+++++ + + + + + + + + + + + + +

font_face	A user font face
render_glyph_func	The render_glyph callback, or `NULL`

Since: 1.8

cairo_user_font_face_get_render_glyph_func ()

cairo_user_scaled_font_render_glyph_func_t
+cairo_user_font_face_get_render_glyph_func
+                               (cairo_font_face_t *font_face);

Gets the glyph rendering function of a user-font.

Parameters

+++++ + + + + + +

font_face

A user font face

Returns

The render_glyph callback of font_face +or NULL if none set or an error has occurred.

Since: 1.8

cairo_user_font_face_set_unicode_to_glyph_func ()

void
+cairo_user_font_face_set_unicode_to_glyph_func
+                               (cairo_font_face_t *font_face,
+                                cairo_user_scaled_font_unicode_to_glyph_func_t unicode_to_glyph_func);

Sets the unicode-to-glyph conversion function of a user-font. +See cairo_user_scaled_font_unicode_to_glyph_func_t for details of how the callback +works.

The font-face should not be immutable or a CAIRO_STATUS_USER_FONT_IMMUTABLE +error will occur. A user font-face is immutable as soon as a scaled-font +is created from it.

Parameters

+++++ + + + + + + + + + + + + +

font_face	A user font face
unicode_to_glyph_func	The unicode_to_glyph callback, or `NULL`

Since: 1.8

cairo_user_font_face_get_unicode_to_glyph_func ()

cairo_user_scaled_font_unicode_to_glyph_func_t
+cairo_user_font_face_get_unicode_to_glyph_func
+                               (cairo_font_face_t *font_face);

Gets the unicode-to-glyph conversion function of a user-font.

Parameters

+++++ + + + + + +

font_face

A user font face

Returns

The unicode_to_glyph callback of font_face +or NULL if none set or an error occurred.

Since: 1.8

cairo_user_font_face_set_text_to_glyphs_func ()

void
+cairo_user_font_face_set_text_to_glyphs_func
+                               (cairo_font_face_t *font_face,
+                                cairo_user_scaled_font_text_to_glyphs_func_t text_to_glyphs_func);

Sets th text-to-glyphs conversion function of a user-font. +See cairo_user_scaled_font_text_to_glyphs_func_t for details of how the callback +works.

The font-face should not be immutable or a CAIRO_STATUS_USER_FONT_IMMUTABLE +error will occur. A user font-face is immutable as soon as a scaled-font +is created from it.

Parameters

+++++ + + + + + + + + + + + + +

font_face	A user font face
text_to_glyphs_func	The text_to_glyphs callback, or `NULL`

Since: 1.8

cairo_user_font_face_get_text_to_glyphs_func ()

cairo_user_scaled_font_text_to_glyphs_func_t
+cairo_user_font_face_get_text_to_glyphs_func
+                               (cairo_font_face_t *font_face);

Gets the text-to-glyphs conversion function of a user-font.

Parameters

+++++ + + + + + +

font_face

A user font face

Returns

The text_to_glyphs callback of font_face +or NULL if none set or an error occurred.

Since: 1.8

Types and Values

CAIRO_HAS_USER_FONT

#define CAIRO_HAS_USER_FONT 1
+

Defined if the user font backend is available. +This macro can be used to conditionally compile backend-specific code. +The user font backend is always built in versions of cairo that support +this feature (1.8 and later).

Since: 1.8