| jpayne@68: Top jpayne@68: | jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: cairo_scaled_font_tjpayne@68:cairo_scaled_font_t — Font face at particular size and options jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: cairo_scaled_font_t * jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_create () jpayne@68: | jpayne@68:
| jpayne@68: cairo_scaled_font_t * jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_reference () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_destroy () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_status () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_extents () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_text_extents () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_glyph_extents () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_text_to_glyphs () jpayne@68: | jpayne@68:
| jpayne@68: cairo_font_face_t * jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_font_face () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_font_options () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_font_matrix () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_ctm () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_scale_matrix () jpayne@68: | jpayne@68:
| jpayne@68: cairo_font_type_t jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_type () jpayne@68: | jpayne@68:
| unsigned int jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_reference_count () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_set_user_data () jpayne@68: | jpayne@68:
| jpayne@68: void * jpayne@68: | jpayne@68:jpayne@68: cairo_scaled_font_get_user_data () jpayne@68: | jpayne@68:
| typedef | jpayne@68:cairo_scaled_font_t | jpayne@68:
| jpayne@68: | cairo_font_extents_t | jpayne@68:
| jpayne@68: | cairo_text_extents_t | jpayne@68:
cairo_scaled_font_t represents a realization of a font face at a particular jpayne@68: size and transformation and a certain set of font options.
jpayne@68:cairo_scaled_font_t * jpayne@68: cairo_scaled_font_create (jpayne@68:cairo_font_face_t *font_face, jpayne@68:const cairo_matrix_t *font_matrix, jpayne@68:const cairo_matrix_t *ctm, jpayne@68:const cairo_font_options_t *options);
Creates a cairo_scaled_font_t object from a font face and matrices that jpayne@68: describe the size of the font and the environment in which it will jpayne@68: be used.
jpayne@68:font_face |
jpayne@68: jpayne@68: | jpayne@68: |
font_matrix |
jpayne@68: font space to user space transformation matrix for the
jpayne@68: font. In the simplest case of a N point font, this matrix is
jpayne@68: just a scale by N, but it can also be used to shear the font
jpayne@68: or stretch it unequally along the two axes. See
jpayne@68: |
jpayne@68: jpayne@68: |
ctm |
jpayne@68: user to device transformation matrix with which the font will jpayne@68: be used. |
jpayne@68: jpayne@68: |
options |
jpayne@68: options to use when getting metrics for the font and jpayne@68: rendering with it. |
jpayne@68: jpayne@68: |
a newly created cairo_scaled_font_t. Destroy with
jpayne@68: cairo_scaled_font_destroy()
Since: 1.0
jpayne@68:cairo_scaled_font_t *
jpayne@68: cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
jpayne@68: Increases the reference count on scaled_font
jpayne@68: by one. This prevents
jpayne@68: scaled_font
jpayne@68: from being destroyed until a matching call to
jpayne@68: cairo_scaled_font_destroy() is made.
Use cairo_scaled_font_get_reference_count() to get the number of
jpayne@68: references to a cairo_scaled_font_t.
scaled_font |
jpayne@68: a cairo_scaled_font_t, (may be |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
jpayne@68: Decreases the reference count on font
jpayne@68: by one. If the result
jpayne@68: is zero, then font
jpayne@68: and all associated resources are freed.
jpayne@68: See cairo_scaled_font_reference().
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:cairo_status_t
jpayne@68: cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
jpayne@68: Checks whether an error has previously occurred for this jpayne@68: scaled_font.
jpayne@68:scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
CAIRO_STATUS_SUCCESS or another error such as
jpayne@68: CAIRO_STATUS_NO_MEMORY.
Since: 1.0
jpayne@68:void jpayne@68: cairo_scaled_font_extents (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:cairo_font_extents_t *extents);
Gets the metrics for a cairo_scaled_font_t.
jpayne@68:scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
extents |
jpayne@68: a cairo_font_extents_t which to store the retrieved extents. |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_scaled_font_text_extents (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:const char *utf8, jpayne@68:cairo_text_extents_t *extents);
Gets the extents for a string of text. The extents describe a
jpayne@68: user-space rectangle that encloses the "inked" portion of the text
jpayne@68: drawn at the origin (0,0) (as it would be drawn by cairo_show_text()
jpayne@68: if the cairo graphics state were set to the same font_face,
jpayne@68: font_matrix, ctm, and font_options as scaled_font
jpayne@68: ). Additionally,
jpayne@68: the x_advance and y_advance values indicate the amount by which the
jpayne@68: current point would be advanced by cairo_show_text().
Note that whitespace characters do not directly contribute to the jpayne@68: size of the rectangle (extents.width and extents.height). They do jpayne@68: contribute indirectly by changing the position of non-whitespace jpayne@68: characters. In particular, trailing whitespace characters are jpayne@68: likely to not affect the size of the rectangle, though they will jpayne@68: affect the x_advance and y_advance values.
jpayne@68:scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
utf8 |
jpayne@68: a NUL-terminated string of text, encoded in UTF-8 |
jpayne@68: jpayne@68: |
extents |
jpayne@68: a cairo_text_extents_t which to store the retrieved extents. |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_scaled_font_glyph_extents (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:const cairo_glyph_t *glyphs, jpayne@68:int num_glyphs, jpayne@68:cairo_text_extents_t *extents);
Gets the extents for an array of glyphs. The extents describe a
jpayne@68: user-space rectangle that encloses the "inked" portion of the
jpayne@68: glyphs, (as they would be drawn by cairo_show_glyphs() if the cairo
jpayne@68: graphics state were set to the same font_face, font_matrix, ctm,
jpayne@68: and font_options as scaled_font
jpayne@68: ). Additionally, the x_advance and
jpayne@68: y_advance values indicate the amount by which the current point
jpayne@68: would be advanced by cairo_show_glyphs().
Note that whitespace glyphs do not contribute to the size of the jpayne@68: rectangle (extents.width and extents.height).
jpayne@68:scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
glyphs |
jpayne@68: an array of glyph IDs with X and Y offsets. |
jpayne@68: jpayne@68: |
num_glyphs |
jpayne@68: the number of glyphs in the |
jpayne@68: jpayne@68: |
extents |
jpayne@68: a cairo_text_extents_t which to store the retrieved extents. |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_status_t jpayne@68: cairo_scaled_font_text_to_glyphs (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:double x, jpayne@68:double y, 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);
Converts UTF-8 text to an array of glyphs, optionally with cluster
jpayne@68: mapping, that can be used to render later using scaled_font
jpayne@68: .
If glyphs
jpayne@68: initially points to a non-NULL value, that array is used
jpayne@68: as a glyph buffer, and num_glyphs
jpayne@68: should point to the number of glyph
jpayne@68: entries available there. If the provided glyph array is too short for
jpayne@68: the conversion, a new glyph array is allocated using cairo_glyph_allocate()
jpayne@68: and placed in glyphs
jpayne@68: . Upon return, num_glyphs
jpayne@68: always contains the
jpayne@68: number of generated glyphs. If the value glyphs
jpayne@68: points to has changed
jpayne@68: after the call, the user is responsible for freeing the allocated glyph
jpayne@68: array using cairo_glyph_free(). This may happen even if the provided
jpayne@68: array was large enough.
If clusters
jpayne@68: is not NULL, num_clusters
jpayne@68: and cluster_flags
jpayne@68: should not be NULL,
jpayne@68: and cluster mapping will be computed.
jpayne@68: The semantics of how cluster array allocation works is similar to the glyph
jpayne@68: array. That is,
jpayne@68: if clusters
jpayne@68: initially points to a non-NULL value, that array is used
jpayne@68: as a cluster buffer, and num_clusters
jpayne@68: should point to the number of cluster
jpayne@68: entries available there. If the provided cluster array is too short for
jpayne@68: the conversion, a new cluster array is allocated using cairo_text_cluster_allocate()
jpayne@68: and placed in clusters
jpayne@68: . Upon return, num_clusters
jpayne@68: always contains the
jpayne@68: number of generated clusters. If the value clusters
jpayne@68: points at has changed
jpayne@68: after the call, the user is responsible for freeing the allocated cluster
jpayne@68: array using cairo_text_cluster_free(). This may happen even if the provided
jpayne@68: array was large enough.
In the simplest case, glyphs
jpayne@68: and clusters
jpayne@68: can point to NULL initially
jpayne@68: and a suitable array will be allocated. In code:
1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 jpayne@68: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 jpayne@68: 17 jpayne@68: 18 jpayne@68: 19 jpayne@68: 20 jpayne@68: 21 jpayne@68: 22 jpayne@68: 23 |
jpayne@68: cairo_status_t status; jpayne@68: jpayne@68: cairo_glyph_t *glyphs = NULL; jpayne@68: int num_glyphs; jpayne@68: cairo_text_cluster_t *clusters = NULL; jpayne@68: int num_clusters; jpayne@68: cairo_text_cluster_flags_t cluster_flags; jpayne@68: jpayne@68: status = cairo_scaled_font_text_to_glyphs (scaled_font, jpayne@68: x, y, jpayne@68: utf8, utf8_len, jpayne@68: &glyphs, &num_glyphs, jpayne@68: &clusters, &num_clusters, &cluster_flags); jpayne@68: jpayne@68: if (status == CAIRO_STATUS_SUCCESS) { jpayne@68: cairo_show_text_glyphs (cr, jpayne@68: utf8, utf8_len, jpayne@68: glyphs, num_glyphs, jpayne@68: clusters, num_clusters, cluster_flags); jpayne@68: jpayne@68: cairo_glyph_free (glyphs); jpayne@68: cairo_text_cluster_free (clusters); jpayne@68: } |
jpayne@68:
If no cluster mapping is needed:
jpayne@68:1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 jpayne@68: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 |
jpayne@68: cairo_status_t status; jpayne@68: jpayne@68: cairo_glyph_t *glyphs = NULL; jpayne@68: int num_glyphs; jpayne@68: jpayne@68: status = cairo_scaled_font_text_to_glyphs (scaled_font, jpayne@68: x, y, jpayne@68: utf8, utf8_len, jpayne@68: &glyphs, &num_glyphs, jpayne@68: NULL, NULL, jpayne@68: NULL); jpayne@68: jpayne@68: if (status == CAIRO_STATUS_SUCCESS) { jpayne@68: cairo_show_glyphs (cr, glyphs, num_glyphs); jpayne@68: cairo_glyph_free (glyphs); jpayne@68: } |
jpayne@68:
If stack-based glyph and cluster arrays are to be used for small jpayne@68: arrays:
jpayne@68:1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 jpayne@68: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 jpayne@68: 17 jpayne@68: 18 jpayne@68: 19 jpayne@68: 20 jpayne@68: 21 jpayne@68: 22 jpayne@68: 23 jpayne@68: 24 jpayne@68: 25 jpayne@68: 26 jpayne@68: 27 |
jpayne@68: cairo_status_t status; jpayne@68: jpayne@68: cairo_glyph_t stack_glyphs[40]; jpayne@68: cairo_glyph_t *glyphs = stack_glyphs; jpayne@68: int num_glyphs = sizeof (stack_glyphs) / sizeof (stack_glyphs[0]); jpayne@68: cairo_text_cluster_t stack_clusters[40]; jpayne@68: cairo_text_cluster_t *clusters = stack_clusters; jpayne@68: int num_clusters = sizeof (stack_clusters) / sizeof (stack_clusters[0]); jpayne@68: cairo_text_cluster_flags_t cluster_flags; jpayne@68: jpayne@68: status = cairo_scaled_font_text_to_glyphs (scaled_font, jpayne@68: x, y, jpayne@68: utf8, utf8_len, jpayne@68: &glyphs, &num_glyphs, jpayne@68: &clusters, &num_clusters, &cluster_flags); jpayne@68: jpayne@68: if (status == CAIRO_STATUS_SUCCESS) { jpayne@68: cairo_show_text_glyphs (cr, jpayne@68: utf8, utf8_len, jpayne@68: glyphs, num_glyphs, jpayne@68: clusters, num_clusters, cluster_flags); jpayne@68: jpayne@68: if (glyphs != stack_glyphs) jpayne@68: cairo_glyph_free (glyphs); jpayne@68: if (clusters != stack_clusters) jpayne@68: cairo_text_cluster_free (clusters); jpayne@68: } |
jpayne@68:
For details of how clusters
jpayne@68: , num_clusters
jpayne@68: , and cluster_flags
jpayne@68: map input
jpayne@68: UTF-8 text to the output glyphs see cairo_show_text_glyphs().
The output values can be readily passed to cairo_show_text_glyphs()
jpayne@68: cairo_show_glyphs(), or related functions, assuming that the exact
jpayne@68: same scaled_font
jpayne@68: is used for the operation.
x |
jpayne@68: X position to place first glyph |
jpayne@68: jpayne@68: |
y |
jpayne@68: Y position to place first glyph |
jpayne@68: jpayne@68: |
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
utf8 |
jpayne@68: a string of text encoded in UTF-8 |
jpayne@68: jpayne@68: |
utf8_len |
jpayne@68: length of |
jpayne@68: jpayne@68: |
glyphs |
jpayne@68: pointer to array of glyphs to fill |
jpayne@68: jpayne@68: |
num_glyphs |
jpayne@68: pointer to number of glyphs |
jpayne@68: jpayne@68: |
clusters |
jpayne@68: pointer to array of cluster mapping information to fill, or |
jpayne@68: jpayne@68: |
num_clusters |
jpayne@68: pointer to number of clusters, or |
jpayne@68: jpayne@68: |
cluster_flags |
jpayne@68: pointer to location to store cluster flags corresponding to the
jpayne@68: output |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS upon success, or an error status
jpayne@68: if the input values are wrong or if conversion failed. If the input
jpayne@68: values are correct but the conversion failed, the error status is also
jpayne@68: set on scaled_font
jpayne@68: .
Since: 1.8
jpayne@68:cairo_font_face_t *
jpayne@68: cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font);
jpayne@68: Gets the font face that this scaled font uses. This might be the
jpayne@68: font face passed to cairo_scaled_font_create(), but this does not
jpayne@68: hold true for all possible cases.
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
The cairo_font_face_t with which scaled_font
jpayne@68: was
jpayne@68: created. This object is owned by cairo. To keep a reference to it,
jpayne@68: you must call cairo_scaled_font_reference().
Since: 1.2
jpayne@68:void jpayne@68: cairo_scaled_font_get_font_options (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:cairo_font_options_t *options);
Stores the font options with which scaled_font
jpayne@68: was created into
jpayne@68: options
jpayne@68: .
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
options |
jpayne@68: return value for the font options |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_scaled_font_get_font_matrix (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:cairo_matrix_t *font_matrix);
Stores the font matrix with which scaled_font
jpayne@68: was created into
jpayne@68: matrix
jpayne@68: .
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
font_matrix |
jpayne@68: return value for the matrix |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_scaled_font_get_ctm (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:cairo_matrix_t *ctm);
Stores the CTM with which scaled_font
jpayne@68: was created into ctm
jpayne@68: .
jpayne@68: Note that the translation offsets (x0, y0) of the CTM are ignored
jpayne@68: by cairo_scaled_font_create(). So, the matrix this
jpayne@68: function returns always has 0,0 as x0,y0.
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
ctm |
jpayne@68: return value for the CTM |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void jpayne@68: cairo_scaled_font_get_scale_matrix (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:cairo_matrix_t *scale_matrix);
Stores the scale matrix of scaled_font
jpayne@68: into matrix
jpayne@68: .
jpayne@68: The scale matrix is product of the font matrix and the ctm
jpayne@68: associated with the scaled font, and hence is the matrix mapping from
jpayne@68: font space to device space.
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
scale_matrix |
jpayne@68: return value for the matrix |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:cairo_font_type_t
jpayne@68: cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);
jpayne@68: This function returns the type of the backend used to create
jpayne@68: a scaled font. See cairo_font_type_t for available types.
jpayne@68: However, this function never returns CAIRO_FONT_TYPE_TOY.
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.2
jpayne@68:unsigned int
jpayne@68: cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font);
jpayne@68: Returns the current reference count of scaled_font
jpayne@68: .
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
the current reference count of scaled_font
jpayne@68: . If the
jpayne@68: object is a nil object, 0 will be returned.
Since: 1.4
jpayne@68:cairo_status_t jpayne@68: cairo_scaled_font_set_user_data (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:const cairo_user_data_key_t *key, jpayne@68:void *user_data, jpayne@68:cairo_destroy_func_t destroy);
Attach user data to scaled_font
jpayne@68: . To remove user data from a surface,
jpayne@68: call this function with the key that was used to set it and NULL
jpayne@68: for data
jpayne@68: .
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
key |
jpayne@68: the address of a cairo_user_data_key_t to attach the user data to |
jpayne@68: jpayne@68: |
user_data |
jpayne@68: the user data to attach to the cairo_scaled_font_t |
jpayne@68: jpayne@68: |
destroy |
jpayne@68: a cairo_destroy_func_t which will be called when the jpayne@68: cairo_t is destroyed or when new user data is attached using the jpayne@68: same key. |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a
jpayne@68: slot could not be allocated for the user data.
Since: 1.4
jpayne@68:void * jpayne@68: cairo_scaled_font_get_user_data (jpayne@68:cairo_scaled_font_t *scaled_font, jpayne@68:const cairo_user_data_key_t *key);
Return user data previously attached to scaled_font
jpayne@68: using the
jpayne@68: specified key. If no user data has been attached with the given
jpayne@68: key this function returns NULL.
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
key |
jpayne@68: the address of the cairo_user_data_key_t the user data was jpayne@68: attached to |
jpayne@68: jpayne@68: |
Since: 1.4
jpayne@68:typedef struct _cairo_scaled_font cairo_scaled_font_t; jpayne@68:jpayne@68:
A cairo_scaled_font_t is a font scaled to a particular size and device jpayne@68: resolution. A cairo_scaled_font_t is most useful for low-level font jpayne@68: usage where a library or application wants to cache a reference jpayne@68: to a scaled font to speed up the computation of metrics.
jpayne@68:There are various types of scaled fonts, depending on the
jpayne@68: font backend they use. The type of a
jpayne@68: scaled font can be queried using cairo_scaled_font_get_type().
Memory management of cairo_scaled_font_t is done with
jpayne@68: cairo_scaled_font_reference() and cairo_scaled_font_destroy().
Since: 1.0
jpayne@68:typedef struct {
jpayne@68: double ascent;
jpayne@68: double descent;
jpayne@68: double height;
jpayne@68: double max_x_advance;
jpayne@68: double max_y_advance;
jpayne@68: } cairo_font_extents_t;
jpayne@68:
jpayne@68: The cairo_font_extents_t structure stores metric information for jpayne@68: a font. Values are given in the current user-space coordinate jpayne@68: system.
jpayne@68:Because font metrics are in user-space coordinates, they are
jpayne@68: mostly, but not entirely, independent of the current transformation
jpayne@68: matrix. If you call cairo_scale(cr, 2.0, 2.0),
jpayne@68: text will be drawn twice as big, but the reported text extents will
jpayne@68: not be doubled. They will change slightly due to hinting (so you
jpayne@68: can't assume that metrics are independent of the transformation
jpayne@68: matrix), but otherwise will remain unchanged.
| jpayne@68: | the distance that the font extends above the baseline. jpayne@68: Note that this is not always exactly equal to the maximum jpayne@68: of the extents of all the glyphs in the font, but rather jpayne@68: is picked to express the font designer's intent as to jpayne@68: how the font should align with elements above it. |
jpayne@68: jpayne@68: |
| jpayne@68: | the distance that the font extends below the baseline. jpayne@68: This value is positive for typical fonts that include jpayne@68: portions below the baseline. Note that this is not always jpayne@68: exactly equal to the maximum of the extents of all the jpayne@68: glyphs in the font, but rather is picked to express the jpayne@68: font designer's intent as to how the font should jpayne@68: align with elements below it. |
jpayne@68: jpayne@68: |
| jpayne@68: | the recommended vertical distance between baselines when
jpayne@68: setting consecutive lines of text with the font. This
jpayne@68: is greater than |
jpayne@68: jpayne@68: |
| jpayne@68: | the maximum distance in the X direction that jpayne@68: the origin is advanced for any glyph in the font. |
jpayne@68: jpayne@68: |
| jpayne@68: | the maximum distance in the Y direction that jpayne@68: the origin is advanced for any glyph in the font. jpayne@68: This will be zero for normal fonts used for horizontal jpayne@68: writing. (The scripts of East Asia are sometimes written jpayne@68: vertically.) |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:typedef struct {
jpayne@68: double x_bearing;
jpayne@68: double y_bearing;
jpayne@68: double width;
jpayne@68: double height;
jpayne@68: double x_advance;
jpayne@68: double y_advance;
jpayne@68: } cairo_text_extents_t;
jpayne@68:
jpayne@68: The cairo_text_extents_t structure stores the extents of a single
jpayne@68: glyph or a string of glyphs in user-space coordinates. Because text
jpayne@68: extents are in user-space coordinates, they are mostly, but not
jpayne@68: entirely, independent of the current transformation matrix. If you call
jpayne@68: cairo_scale(cr, 2.0, 2.0), text will
jpayne@68: be drawn twice as big, but the reported text extents will not be
jpayne@68: doubled. They will change slightly due to hinting (so you can't
jpayne@68: assume that metrics are independent of the transformation matrix),
jpayne@68: but otherwise will remain unchanged.
| jpayne@68: | the horizontal distance from the origin to the jpayne@68: leftmost part of the glyphs as drawn. Positive if the jpayne@68: glyphs lie entirely to the right of the origin. |
jpayne@68: jpayne@68: |
| jpayne@68: | the vertical distance from the origin to the jpayne@68: topmost part of the glyphs as drawn. Positive only if the jpayne@68: glyphs lie completely below the origin; will usually be jpayne@68: negative. |
jpayne@68: jpayne@68: |
| jpayne@68: | width of the glyphs as drawn |
jpayne@68: jpayne@68: |
| jpayne@68: | height of the glyphs as drawn |
jpayne@68: jpayne@68: |
| jpayne@68: | distance to advance in the X direction jpayne@68: after drawing these glyphs |
jpayne@68: jpayne@68: |
| jpayne@68: | distance to advance in the Y direction jpayne@68: after drawing these glyphs. Will typically be zero except jpayne@68: for vertical text layout as found in East-Asian languages. |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68: