cairo_scaled_font_t: Cairo: A Vector Graphics Library

+ + +

cairo_scaled_font_t

cairo_scaled_font_t — Font face at particular size and options

Functions

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

+cairo_scaled_font_t * +	+cairo_scaled_font_create () +
+cairo_scaled_font_t * +	+cairo_scaled_font_reference () +
+void +	+cairo_scaled_font_destroy () +
+cairo_status_t +	+cairo_scaled_font_status () +
+void +	+cairo_scaled_font_extents () +
+void +	+cairo_scaled_font_text_extents () +
+void +	+cairo_scaled_font_glyph_extents () +
+cairo_status_t +	+cairo_scaled_font_text_to_glyphs () +
+cairo_font_face_t * +	+cairo_scaled_font_get_font_face () +
+void +	+cairo_scaled_font_get_font_options () +
+void +	+cairo_scaled_font_get_font_matrix () +
+void +	+cairo_scaled_font_get_ctm () +
+void +	+cairo_scaled_font_get_scale_matrix () +
+cairo_font_type_t +	+cairo_scaled_font_get_type () +
unsigned int +	+cairo_scaled_font_get_reference_count () +
+cairo_status_t +	+cairo_scaled_font_set_user_data () +
+void * +	+cairo_scaled_font_get_user_data () +

Types and Values

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

typedef	cairo_scaled_font_t
	cairo_font_extents_t
	cairo_text_extents_t

Description

cairo_scaled_font_t represents a realization of a font face at a particular +size and transformation and a certain set of font options.

Functions

cairo_scaled_font_create ()

cairo_scaled_font_t *
+cairo_scaled_font_create (cairo_font_face_t *font_face,
+                          const cairo_matrix_t *font_matrix,
+                          const cairo_matrix_t *ctm,
+                          const cairo_font_options_t *options);

Creates a cairo_scaled_font_t object from a font face and matrices that +describe the size of the font and the environment in which it will +be used.

Parameters

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

font_face	a cairo_font_face_t
font_matrix	font space to user space transformation matrix for the +font. In the simplest case of a N point font, this matrix is +just a scale by N, but it can also be used to shear the font +or stretch it unequally along the two axes. See +`cairo_set_font_matrix()`.
ctm	user to device transformation matrix with which the font will +be used.
options	options to use when getting metrics for the font and +rendering with it.

Returns

a newly created cairo_scaled_font_t. Destroy with +cairo_scaled_font_destroy()

Since: 1.0

cairo_scaled_font_reference ()

cairo_scaled_font_t *
+cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);

Increases the reference count on scaled_font + by one. This prevents +scaled_font + from being destroyed until a matching call to +cairo_scaled_font_destroy() is made.

Use cairo_scaled_font_get_reference_count() to get the number of +references to a cairo_scaled_font_t.

Parameters

+++++ + + + + + +

scaled_font

a cairo_scaled_font_t, (may be NULL in which case +this function does nothing)

Returns

the referenced cairo_scaled_font_t

Since: 1.0

cairo_scaled_font_destroy ()

void
+cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);

Decreases the reference count on font + by one. If the result +is zero, then font + and all associated resources are freed. +See cairo_scaled_font_reference().

Parameters

+++++ + + + + + +

scaled_font

a cairo_scaled_font_t

Since: 1.0

cairo_scaled_font_status ()

cairo_status_t
+cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);

Checks whether an error has previously occurred for this +scaled_font.

Parameters

+++++ + + + + + +

scaled_font

a cairo_scaled_font_t

Returns

CAIRO_STATUS_SUCCESS or another error such as +CAIRO_STATUS_NO_MEMORY.

Since: 1.0

cairo_scaled_font_extents ()

void
+cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font,
+                           cairo_font_extents_t *extents);

Gets the metrics for a cairo_scaled_font_t.

Parameters

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

scaled_font	a cairo_scaled_font_t
extents	a cairo_font_extents_t which to store the retrieved extents.

Since: 1.0

cairo_scaled_font_text_extents ()

void
+cairo_scaled_font_text_extents (cairo_scaled_font_t *scaled_font,
+                                const char *utf8,
+                                cairo_text_extents_t *extents);

Gets the extents for a string of text. The extents describe a +user-space rectangle that encloses the "inked" portion of the text +drawn at the origin (0,0) (as it would be drawn by cairo_show_text() +if the cairo graphics state were set to the same font_face, +font_matrix, ctm, and font_options as scaled_font +). Additionally, +the x_advance and y_advance values indicate the amount by which the +current point would be advanced by cairo_show_text().

Note that whitespace characters do not directly contribute to the +size of the rectangle (extents.width and extents.height). They do +contribute indirectly by changing the position of non-whitespace +characters. In particular, trailing whitespace characters are +likely to not affect the size of the rectangle, though they will +affect the x_advance and y_advance values.

Parameters

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

scaled_font	a cairo_scaled_font_t
utf8	a NUL-terminated string of text, encoded in UTF-8
extents	a cairo_text_extents_t which to store the retrieved extents.

Since: 1.2

cairo_scaled_font_glyph_extents ()

void
+cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
+                                 const cairo_glyph_t *glyphs,
+                                 int num_glyphs,
+                                 cairo_text_extents_t *extents);

Gets the extents for an array of glyphs. The extents describe a +user-space rectangle that encloses the "inked" portion of the +glyphs, (as they would be drawn by cairo_show_glyphs() if the cairo +graphics state were set to the same font_face, font_matrix, ctm, +and font_options as scaled_font +). Additionally, the x_advance and +y_advance values indicate the amount by which the current point +would be advanced by cairo_show_glyphs().

Note that whitespace glyphs do not contribute to the size of the +rectangle (extents.width and extents.height).

Parameters

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

scaled_font	a cairo_scaled_font_t
glyphs	an array of glyph IDs with X and Y offsets.
num_glyphs	the number of glyphs in the `glyphs` +array
extents	a cairo_text_extents_t which to store the retrieved extents.

Since: 1.0

cairo_scaled_font_text_to_glyphs ()

cairo_status_t
+cairo_scaled_font_text_to_glyphs (cairo_scaled_font_t *scaled_font,
+                                  double x,
+                                  double y,
+                                  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);

Converts UTF-8 text to an array of glyphs, optionally with cluster +mapping, that can be used to render later using scaled_font +.

If glyphs + initially points to a non-NULL value, that array is used +as a glyph buffer, and num_glyphs + should point to the number of glyph +entries available there. If the provided glyph array is too short for +the conversion, a new glyph array is allocated using cairo_glyph_allocate() +and placed in glyphs +. Upon return, num_glyphs + always contains the +number of generated glyphs. If the value glyphs + points to has changed +after the call, the user is responsible for freeing the allocated glyph +array using cairo_glyph_free(). This may happen even if the provided +array was large enough.

If clusters + is not NULL, num_clusters + and cluster_flags + should not be NULL, +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 is used +as a cluster buffer, and num_clusters + should point to the number of cluster +entries available there. If the provided cluster array is too short for +the conversion, a new cluster array is allocated using cairo_text_cluster_allocate() +and placed in clusters +. Upon return, num_clusters + always contains the +number of generated clusters. If the value clusters + points at has changed +after the call, the user is responsible for freeing the allocated cluster +array using cairo_text_cluster_free(). This may happen even if the provided +array was large enough.

In the simplest case, glyphs + and clusters + can point to NULL initially +and a suitable array will be allocated. In code:

+ + + + + + + +

1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23

cairo_status_t status;
+
+cairo_glyph_t *glyphs = NULL;
+int num_glyphs;
+cairo_text_cluster_t *clusters = NULL;
+int num_clusters;
+cairo_text_cluster_flags_t cluster_flags;
+
+status = cairo_scaled_font_text_to_glyphs (scaled_font,
+                                           x, y,
+                                           utf8, utf8_len,
+                                           &glyphs, &num_glyphs,
+                                           &clusters, &num_clusters, &cluster_flags);
+
+if (status == CAIRO_STATUS_SUCCESS) {
+    cairo_show_text_glyphs (cr,
+                            utf8, utf8_len,
+                            glyphs, num_glyphs,
+                            clusters, num_clusters, cluster_flags);
+
+    cairo_glyph_free (glyphs);
+    cairo_text_cluster_free (clusters);
+}

+ +

If no cluster mapping is needed:

+ + + + + + + +

1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16

cairo_status_t status;
+
+cairo_glyph_t *glyphs = NULL;
+int num_glyphs;
+
+status = cairo_scaled_font_text_to_glyphs (scaled_font,
+                                           x, y,
+                                           utf8, utf8_len,
+                                           &glyphs, &num_glyphs,
+                                           NULL, NULL,
+                                           NULL);
+
+if (status == CAIRO_STATUS_SUCCESS) {
+    cairo_show_glyphs (cr, glyphs, num_glyphs);
+    cairo_glyph_free (glyphs);
+}

+ +

If stack-based glyph and cluster arrays are to be used for small +arrays:

+ + + + + + + +

1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27

cairo_status_t status;
+
+cairo_glyph_t stack_glyphs[40];
+cairo_glyph_t *glyphs = stack_glyphs;
+int num_glyphs = sizeof (stack_glyphs) / sizeof (stack_glyphs[0]);
+cairo_text_cluster_t stack_clusters[40];
+cairo_text_cluster_t *clusters = stack_clusters;
+int num_clusters = sizeof (stack_clusters) / sizeof (stack_clusters[0]);
+cairo_text_cluster_flags_t cluster_flags;
+
+status = cairo_scaled_font_text_to_glyphs (scaled_font,
+                                           x, y,
+                                           utf8, utf8_len,
+                                           &glyphs, &num_glyphs,
+                                           &clusters, &num_clusters, &cluster_flags);
+
+if (status == CAIRO_STATUS_SUCCESS) {
+    cairo_show_text_glyphs (cr,
+                            utf8, utf8_len,
+                            glyphs, num_glyphs,
+                            clusters, num_clusters, cluster_flags);
+
+    if (glyphs != stack_glyphs)
+        cairo_glyph_free (glyphs);
+    if (clusters != stack_clusters)
+        cairo_text_cluster_free (clusters);
+}

+ +

For details of how clusters +, num_clusters +, and cluster_flags + map input +UTF-8 text to the output glyphs see cairo_show_text_glyphs().

The output values can be readily passed to cairo_show_text_glyphs() +cairo_show_glyphs(), or related functions, assuming that the exact +same scaled_font + is used for the operation.

Parameters

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

x	X position to place first glyph
y	Y position to place first glyph
scaled_font	a cairo_scaled_font_t
utf8	a string of text encoded in UTF-8
utf8_len	length of `utf8` +in bytes, or -1 if it is NUL-terminated
glyphs	pointer to array of glyphs to fill
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, or `NULL`
cluster_flags	pointer to location to store cluster flags corresponding to the +output `clusters` +, or `NULL`

Returns

CAIRO_STATUS_SUCCESS upon success, or an error status +if the input values are wrong or if conversion failed. If the input +values are correct but the conversion failed, the error status is also +set on scaled_font +.

Since: 1.8

cairo_scaled_font_get_font_face ()

cairo_font_face_t *
+cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font);

Gets the font face that this scaled font uses. This might be the +font face passed to cairo_scaled_font_create(), but this does not +hold true for all possible cases.

Parameters

+++++ + + + + + +

scaled_font

a cairo_scaled_font_t

Returns

The cairo_font_face_t with which scaled_font +was +created. This object is owned by cairo. To keep a reference to it, +you must call cairo_scaled_font_reference().

Since: 1.2

cairo_scaled_font_get_font_options ()

void
+cairo_scaled_font_get_font_options (cairo_scaled_font_t *scaled_font,
+                                    cairo_font_options_t *options);

Stores the font options with which scaled_font + was created into +options +.

Parameters

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

scaled_font	a cairo_scaled_font_t
options	return value for the font options

Since: 1.2

cairo_scaled_font_get_font_matrix ()

void
+cairo_scaled_font_get_font_matrix (cairo_scaled_font_t *scaled_font,
+                                   cairo_matrix_t *font_matrix);

Stores the font matrix with which scaled_font + was created into +matrix +.

Parameters

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

scaled_font	a cairo_scaled_font_t
font_matrix	return value for the matrix

Since: 1.2

cairo_scaled_font_get_ctm ()

void
+cairo_scaled_font_get_ctm (cairo_scaled_font_t *scaled_font,
+                           cairo_matrix_t *ctm);

Stores the CTM with which scaled_font + was created into ctm +. +Note that the translation offsets (x0, y0) of the CTM are ignored +by cairo_scaled_font_create(). So, the matrix this +function returns always has 0,0 as x0,y0.

Parameters

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

scaled_font	a cairo_scaled_font_t
ctm	return value for the CTM

Since: 1.2

cairo_scaled_font_get_scale_matrix ()

void
+cairo_scaled_font_get_scale_matrix (cairo_scaled_font_t *scaled_font,
+                                    cairo_matrix_t *scale_matrix);

Stores the scale matrix of scaled_font + into matrix +. +The scale matrix is product of the font matrix and the ctm +associated with the scaled font, and hence is the matrix mapping from +font space to device space.

Parameters

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

scaled_font	a cairo_scaled_font_t
scale_matrix	return value for the matrix

Since: 1.8

cairo_scaled_font_get_type ()

cairo_font_type_t
+cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);

This function returns the type of the backend used to create +a scaled font. See cairo_font_type_t for available types. +However, this function never returns CAIRO_FONT_TYPE_TOY.

Parameters

+++++ + + + + + +

scaled_font

a cairo_scaled_font_t

Returns

The type of scaled_font +.

Since: 1.2

cairo_scaled_font_get_reference_count ()

unsigned int
+cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font);

Returns the current reference count of scaled_font +.

Parameters

+++++ + + + + + +

scaled_font

a cairo_scaled_font_t

Returns

the current reference count of scaled_font +. If the +object is a nil object, 0 will be returned.

Since: 1.4

cairo_scaled_font_set_user_data ()

cairo_status_t
+cairo_scaled_font_set_user_data (cairo_scaled_font_t *scaled_font,
+                                 const cairo_user_data_key_t *key,
+                                 void *user_data,
+                                 cairo_destroy_func_t destroy);

Attach user data to scaled_font +. To remove user data from a surface, +call this function with the key that was used to set it and NULL +for data +.

Parameters

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

scaled_font	a cairo_scaled_font_t
key	the address of a cairo_user_data_key_t to attach the user data to
user_data	the user data to attach to the cairo_scaled_font_t
destroy	a cairo_destroy_func_t which will be called when the +cairo_t is destroyed or when new user data is attached using the +same key.

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a +slot could not be allocated for the user data.

Since: 1.4

cairo_scaled_font_get_user_data ()

void *
+cairo_scaled_font_get_user_data (cairo_scaled_font_t *scaled_font,
+                                 const cairo_user_data_key_t *key);

Return user data previously attached to scaled_font + using the +specified key. If no user data has been attached with the given +key this function returns NULL.

Parameters

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

scaled_font	a cairo_scaled_font_t
key	the address of the cairo_user_data_key_t the user data was +attached to

Returns

the user data previously attached or NULL.

Since: 1.4

Types and Values

cairo_scaled_font_t

typedef struct _cairo_scaled_font cairo_scaled_font_t;
+

A cairo_scaled_font_t is a font scaled to a particular size and device +resolution. A cairo_scaled_font_t is most useful for low-level font +usage where a library or application wants to cache a reference +to a scaled font to speed up the computation of metrics.

There are various types of scaled fonts, depending on the +font backend they use. The type of a +scaled font can be queried using cairo_scaled_font_get_type().

Memory management of cairo_scaled_font_t is done with +cairo_scaled_font_reference() and cairo_scaled_font_destroy().

Since: 1.0

cairo_font_extents_t

typedef struct {
+    double ascent;
+    double descent;
+    double height;
+    double max_x_advance;
+    double max_y_advance;
+} cairo_font_extents_t;
+

The cairo_font_extents_t structure stores metric information for +a font. Values are given in the current user-space coordinate +system.

Because font metrics are in user-space coordinates, they are +mostly, but not entirely, independent of the current transformation +matrix. If you call cairo_scale(cr, 2.0, 2.0), +text will be drawn twice as big, but the reported text extents will +not be doubled. They will change slightly due to hinting (so you +can't assume that metrics are independent of the transformation +matrix), but otherwise will remain unchanged.

Members

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

double `ascent`;	the distance that the font extends above the baseline. +Note that this is not always exactly equal to the maximum +of the extents of all the glyphs in the font, but rather +is picked to express the font designer's intent as to +how the font should align with elements above it.
double `descent`;	the distance that the font extends below the baseline. +This value is positive for typical fonts that include +portions below the baseline. Note that this is not always +exactly equal to the maximum of the extents of all the +glyphs in the font, but rather is picked to express the +font designer's intent as to how the font should +align with elements below it.
double `height`;	the recommended vertical distance between baselines when +setting consecutive lines of text with the font. This +is greater than `ascent` ++`descent` +by a +quantity known as the line spacing +or external leading. When space +is at a premium, most fonts can be set with only +a distance of `ascent` ++`descent` +between lines.
double `max_x_advance`;	the maximum distance in the X direction that +the origin is advanced for any glyph in the font.
double `max_y_advance`;	the maximum distance in the Y direction that +the origin is advanced for any glyph in the font. +This will be zero for normal fonts used for horizontal +writing. (The scripts of East Asia are sometimes written +vertically.)

Since: 1.0

cairo_text_extents_t

typedef struct {
+    double x_bearing;
+    double y_bearing;
+    double width;
+    double height;
+    double x_advance;
+    double y_advance;
+} cairo_text_extents_t;
+

The cairo_text_extents_t structure stores the extents of a single +glyph or a string of glyphs in user-space coordinates. Because text +extents are in user-space coordinates, they are mostly, but not +entirely, independent of the current transformation matrix. If you call +cairo_scale(cr, 2.0, 2.0), text will +be drawn twice as big, but the reported text extents will not be +doubled. They will change slightly due to hinting (so you can't +assume that metrics are independent of the transformation matrix), +but otherwise will remain unchanged.

Members

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

double `x_bearing`;	the horizontal distance from the origin to the +leftmost part of the glyphs as drawn. Positive if the +glyphs lie entirely to the right of the origin.
double `y_bearing`;	the vertical distance from the origin to the +topmost part of the glyphs as drawn. Positive only if the +glyphs lie completely below the origin; will usually be +negative.
double `width`;	width of the glyphs as drawn
double `height`;	height of the glyphs as drawn
double `x_advance`;	distance to advance in the X direction +after drawing these glyphs
double `y_advance`;	distance to advance in the Y direction +after drawing these glyphs. Will typically be zero except +for vertical text layout as found in East-Asian languages.

Since: 1.0

cairo_scaled_font_t

Functions

Types and Values

Description

Functions

cairo_scaled_font_create ()

Parameters

Returns

cairo_scaled_font_reference ()

Parameters

Returns

cairo_scaled_font_destroy ()

Parameters

cairo_scaled_font_status ()

Parameters

Returns

cairo_scaled_font_extents ()

Parameters

cairo_scaled_font_text_extents ()

Parameters

cairo_scaled_font_glyph_extents ()

Parameters

cairo_scaled_font_text_to_glyphs ()

Parameters

Returns

cairo_scaled_font_get_font_face ()

Parameters

Returns

cairo_scaled_font_get_font_options ()

Parameters

cairo_scaled_font_get_font_matrix ()

Parameters

cairo_scaled_font_get_ctm ()

Parameters

cairo_scaled_font_get_scale_matrix ()

Parameters

cairo_scaled_font_get_type ()

Parameters

Returns

cairo_scaled_font_get_reference_count ()

Parameters

Returns

cairo_scaled_font_set_user_data ()

Parameters

Returns

cairo_scaled_font_get_user_data ()

Parameters

Returns

Types and Values

cairo_scaled_font_t

cairo_font_extents_t

Members

cairo_text_extents_t

Members

See Also