User Fonts: Cairo: A Vector Graphics Library

jpayne@68:

jpayne@68: jpayne@68: jpayne@68:

jpayne@68:

User Fonts

jpayne@68:

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

jpayne@68:

Functions

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

jpayne@68: cairo_status_t jpayne@68:	jpayne@68: (*cairo_user_scaled_font_init_func_t) () jpayne@68:
jpayne@68: cairo_status_t jpayne@68:	jpayne@68: (*cairo_user_scaled_font_render_glyph_func_t) () jpayne@68:
jpayne@68: cairo_status_t jpayne@68:	jpayne@68: (*cairo_user_scaled_font_text_to_glyphs_func_t) () jpayne@68:
jpayne@68: cairo_status_t jpayne@68:	jpayne@68: (*cairo_user_scaled_font_unicode_to_glyph_func_t) () jpayne@68:
jpayne@68: cairo_font_face_t * jpayne@68:	jpayne@68: cairo_user_font_face_create () jpayne@68:
jpayne@68: void jpayne@68:	jpayne@68: cairo_user_font_face_set_init_func () jpayne@68:
jpayne@68: cairo_user_scaled_font_init_func_t jpayne@68:	jpayne@68: cairo_user_font_face_get_init_func () jpayne@68:
jpayne@68: void jpayne@68:	jpayne@68: cairo_user_font_face_set_render_glyph_func () jpayne@68:
jpayne@68: cairo_user_scaled_font_render_glyph_func_t jpayne@68:	jpayne@68: cairo_user_font_face_get_render_glyph_func () jpayne@68:
jpayne@68: void jpayne@68:	jpayne@68: cairo_user_font_face_set_unicode_to_glyph_func () jpayne@68:
jpayne@68: cairo_user_scaled_font_unicode_to_glyph_func_t jpayne@68:	jpayne@68: cairo_user_font_face_get_unicode_to_glyph_func () jpayne@68:
jpayne@68: void jpayne@68:	jpayne@68: cairo_user_font_face_set_text_to_glyphs_func () jpayne@68:
jpayne@68: cairo_user_scaled_font_text_to_glyphs_func_t jpayne@68:	jpayne@68: cairo_user_font_face_get_text_to_glyphs_func () jpayne@68:

jpayne@68:

Types and Values

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

#define

CAIRO_HAS_USER_FONT

jpayne@68:

Description

jpayne@68:

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

jpayne@68:

Functions

jpayne@68:

cairo_user_scaled_font_init_func_t ()

jpayne@68:

cairo_status_t
jpayne@68: (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t *scaled_font,
jpayne@68:                                        cairo_t *cr,
jpayne@68:                                        cairo_font_extents_t *extents);

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

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

jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS upon success, or an error status on error.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_scaled_font_render_glyph_func_t ()

jpayne@68:

cairo_status_t
jpayne@68: (*cairo_user_scaled_font_render_glyph_func_t)
jpayne@68:                                (cairo_scaled_font_t *scaled_font,
jpayne@68:                                 unsigned long  glyph,
jpayne@68:                                 cairo_t *cr,
jpayne@68:                                 cairo_text_extents_t *extents);

jpayne@68:

cairo_user_scaled_font_render_glyph_func_t is the type of function which jpayne@68: is called when a user scaled-font needs to render a glyph.

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

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

jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS upon success, or jpayne@68: CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_scaled_font_text_to_glyphs_func_t ()

jpayne@68:

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

jpayne@68:

cairo_user_scaled_font_text_to_glyphs_func_t is the type of function which jpayne@68: is called to convert input text to an array of glyphs. This is used by the jpayne@68: cairo_show_text() operation.

jpayne@68:

Using this callback the user-font has full control on glyphs and their jpayne@68: positions. That means, it allows for features like ligatures and kerning, jpayne@68: as well as complex shaping required for scripts like jpayne@68: Arabic and Indic.

jpayne@68:

The num_glyphs jpayne@68: argument is preset to the number of glyph entries available jpayne@68: in the glyphs jpayne@68: buffer. If the glyphs jpayne@68: buffer is NULL, the value of jpayne@68: num_glyphs jpayne@68: will be zero. If the provided glyph array is too short for jpayne@68: the conversion (or for convenience), a new glyph array may be allocated jpayne@68: using cairo_glyph_allocate() and placed in glyphs jpayne@68: . Upon return, jpayne@68: num_glyphs jpayne@68: should contain the number of generated glyphs. If the value jpayne@68: glyphs jpayne@68: points at has changed after the call, the caller will free the jpayne@68: allocated glyph array using cairo_glyph_free(). The caller will also free jpayne@68: the original value of glyphs jpayne@68: , so the callback shouldn't do so. jpayne@68: The callback should populate the glyph indices and positions (in font space) jpayne@68: assuming that the text is to be shown at the origin.

jpayne@68:

If clusters jpayne@68: is not NULL, num_clusters jpayne@68: and cluster_flags jpayne@68: are also jpayne@68: non-NULL, and cluster mapping should be computed. The semantics of how jpayne@68: cluster array allocation works is similar to the glyph array. That is, jpayne@68: if clusters jpayne@68: initially points to a non-NULL value, that array may be used jpayne@68: as a cluster buffer, and num_clusters jpayne@68: points to the number of cluster jpayne@68: entries available there. If the provided cluster array is too short for jpayne@68: the conversion (or for convenience), a new cluster array may be allocated jpayne@68: using cairo_text_cluster_allocate() and placed in clusters jpayne@68: . In this case, jpayne@68: the original value of clusters jpayne@68: will still be freed by the caller. Upon jpayne@68: return, num_clusters jpayne@68: should contain the number of generated clusters. jpayne@68: If the value clusters jpayne@68: points at has changed after the call, the caller jpayne@68: will free the allocated cluster array using cairo_text_cluster_free().

jpayne@68:

The callback is optional. If num_glyphs jpayne@68: is negative upon jpayne@68: the callback returning or if the return value jpayne@68: is CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback jpayne@68: is tried. See cairo_user_scaled_font_unicode_to_glyph_func_t.

jpayne@68:

Note: While cairo does not impose any limitation on glyph indices, jpayne@68: some applications may assume that a glyph index fits in a 16-bit jpayne@68: unsigned integer. As such, it is advised that user-fonts keep their jpayne@68: glyphs in the 0 to 65535 range. Furthermore, some applications may jpayne@68: assume that glyph 0 is a special glyph-not-found glyph. User-fonts jpayne@68: are advised to use glyph 0 for such purposes and do not use that jpayne@68: glyph value for other purposes.

jpayne@68:

Parameters

jpayne@68:

scaled_font	the scaled-font being created
utf8	a string of text encoded in UTF-8
utf8_len	length of `utf8` jpayne@68: 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 jpayne@68: output `clusters` jpayne@68:

jpayne@68:

Returns

jpayne@68:

CAIRO_STATUS_SUCCESS upon success, jpayne@68: CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, jpayne@68: or CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_scaled_font_unicode_to_glyph_func_t ()

jpayne@68:

cairo_status_t
jpayne@68: (*cairo_user_scaled_font_unicode_to_glyph_func_t)
jpayne@68:                                (cairo_scaled_font_t *scaled_font,
jpayne@68:                                 unsigned long  unicode,
jpayne@68:                                 unsigned long *glyph_index);

jpayne@68:

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

jpayne@68:

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

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

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

jpayne@68:

Returns

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_create ()

jpayne@68:

cairo_font_face_t *
jpayne@68: cairo_user_font_face_create (void);

jpayne@68:

Creates a new user font-face.

jpayne@68:

Use the setter functions to associate callbacks with the returned jpayne@68: user font. The only mandatory callback is render_glyph.

jpayne@68:

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

jpayne@68:

Returns

jpayne@68:

a newly created cairo_font_face_t. Free with jpayne@68: cairo_font_face_destroy() when you are done using it.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_set_init_func ()

jpayne@68:

void
jpayne@68: cairo_user_font_face_set_init_func (cairo_font_face_t *font_face,
jpayne@68:                                     cairo_user_scaled_font_init_func_t init_func);

jpayne@68:

Sets the scaled-font initialization function of a user-font. jpayne@68: See cairo_user_scaled_font_init_func_t for details of how the callback jpayne@68: works.

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_get_init_func ()

jpayne@68:

cairo_user_scaled_font_init_func_t
jpayne@68: cairo_user_font_face_get_init_func (cairo_font_face_t *font_face);

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

font_face

A user font face

jpayne@68:

Returns

jpayne@68:

The init callback of font_face jpayne@68: or NULL if none set or an error has occurred.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_set_render_glyph_func ()

jpayne@68:

void
jpayne@68: cairo_user_font_face_set_render_glyph_func
jpayne@68:                                (cairo_font_face_t *font_face,
jpayne@68:                                 cairo_user_scaled_font_render_glyph_func_t render_glyph_func);

jpayne@68:

Sets the glyph rendering function of a user-font. jpayne@68: See cairo_user_scaled_font_render_glyph_func_t for details of how the callback jpayne@68: works.

jpayne@68:

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

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_get_render_glyph_func ()

jpayne@68:

cairo_user_scaled_font_render_glyph_func_t
jpayne@68: cairo_user_font_face_get_render_glyph_func
jpayne@68:                                (cairo_font_face_t *font_face);

jpayne@68:

Gets the glyph rendering function of a user-font.

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

font_face

A user font face

jpayne@68:

Returns

jpayne@68:

The render_glyph callback of font_face jpayne@68: or NULL if none set or an error has occurred.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_set_unicode_to_glyph_func ()

jpayne@68:

void
jpayne@68: cairo_user_font_face_set_unicode_to_glyph_func
jpayne@68:                                (cairo_font_face_t *font_face,
jpayne@68:                                 cairo_user_scaled_font_unicode_to_glyph_func_t unicode_to_glyph_func);

jpayne@68:

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

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_get_unicode_to_glyph_func ()

jpayne@68:

cairo_user_scaled_font_unicode_to_glyph_func_t
jpayne@68: cairo_user_font_face_get_unicode_to_glyph_func
jpayne@68:                                (cairo_font_face_t *font_face);

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

font_face

A user font face

jpayne@68:

Returns

jpayne@68:

The unicode_to_glyph callback of font_face jpayne@68: or NULL if none set or an error occurred.

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_set_text_to_glyphs_func ()

jpayne@68:

void
jpayne@68: cairo_user_font_face_set_text_to_glyphs_func
jpayne@68:                                (cairo_font_face_t *font_face,
jpayne@68:                                 cairo_user_scaled_font_text_to_glyphs_func_t text_to_glyphs_func);

jpayne@68:

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

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

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

jpayne@68:

Since: 1.8

jpayne@68:

cairo_user_font_face_get_text_to_glyphs_func ()

jpayne@68:

cairo_user_scaled_font_text_to_glyphs_func_t
jpayne@68: cairo_user_font_face_get_text_to_glyphs_func
jpayne@68:                                (cairo_font_face_t *font_face);

jpayne@68:

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

jpayne@68:

Parameters

jpayne@68:

jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68: jpayne@68:

font_face

A user font face

jpayne@68:

Returns

jpayne@68:

The text_to_glyphs callback of font_face jpayne@68: or NULL if none set or an error occurred.

jpayne@68:

Since: 1.8

jpayne@68:

Types and Values

jpayne@68:

CAIRO_HAS_USER_FONT

jpayne@68:

#define CAIRO_HAS_USER_FONT 1
jpayne@68:

jpayne@68:

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

jpayne@68:

Since: 1.8

jpayne@68: