Next: Font Options, Previous: Font Faces, Up: Top [Index]
Font face at particular size and options
<cairo-scaled-font> represents a realization of a font face at
a particular size and transformation and a certain set of font options.
<cairo-font-face-t>) (font-matrix <cairo-matrix-t>) (ctm <cairo-matrix-t>) (options <cairo-font-options-t>) ⇒ (ret <cairo-scaled-font-t >)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.
a <cairo-font-face-t>
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.
user to device transformation matrix with which the font will be used.
options to use when getting metrics for the font and rendering with it.
a newly created <cairo-scaled-font-t>. Destroy with
cairo-scaled-font-destroy
<cairo-scaled-font-t>) (extents <cairo-font-extents-t>)Gets the metrics for a <cairo-scaled-font-t>.
a <cairo-scaled-font-t>
a <cairo-font-extents-t> which to store the retrieved extents.
<cairo-scaled-font-t>) (utf8 <char>) (extents <cairo-text-extents-t>)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.
a <cairo-scaled-font-t>
a NUL-terminated string of text, encoded in UTF-8
a <cairo-text-extents-t> which to store the retrieved extents.
Since 1.2
<cairo-scaled-font-t>) (glyphs <cairo-glyph-t>) (num-glyphs <int>) (extents <cairo-text-extents-t>)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).
a <cairo-scaled-font-t>
an array of glyph IDs with X and Y offsets.
the number of glyphs in the glyphs array
a <cairo-text-extents-t> which to store the retrieved extents.
<cairo-scaled-font-t>) (x <double>) (y <double>) (utf8 <char>) (utf8-len <int>) ⇒ (ret <cairo-status-t>) (glyphs <cairo-glyph-t*>) (num-glyphs <int>) (clusters <cairo-text-cluster-t*>) (num-clusters <int>) (cluster-flags <cairo-text-cluster-flags-t>)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-‘#f’ 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 ‘#f’, num-clusters and
cluster-flags should not be ‘#f’, 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-‘#f’ 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
‘#f’ initially and a suitable array will be allocated. In
code:
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:
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:
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-glyphscairo-show-glyphs, or related
functions, assuming that the exact same scaled-font is used for
the operation.
a <cairo-scaled-font-t>
X position to place first glyph
Y position to place first glyph
a string of text encoded in UTF-8
length of utf8 in bytes, or -1 if it is NUL-terminated
pointer to array of glyphs to fill
pointer to number of glyphs
pointer to array of cluster mapping information to fill, or
‘#f’
pointer to number of clusters, or ‘#f’
pointer to location to store cluster flags corresponding to the output
clusters, or ‘#f’
‘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-t>) ⇒ (ret <cairo-font-face-t >)Gets the font face that this scaled font uses. This is the font face
passed to cairo-scaled-font-create.
a <cairo-scaled-font-t>
The <cairo-font-face-t> with which scaled-font was created.
Since 1.2
<cairo-scaled-font-t>) (options <cairo-font-options-t>)Stores the font options with which scaled-font was created into options.
a <cairo-scaled-font-t>
return value for the font options
Since 1.2
<cairo-scaled-font-t>) (font-matrix <cairo-matrix-t>)Stores the font matrix with which scaled-font was created into matrix.
a <cairo-scaled-font-t>
return value for the matrix
Since 1.2
<cairo-scaled-font-t>) (ctm <cairo-matrix-t>)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.
a <cairo-scaled-font-t>
return value for the CTM
Since 1.2
<cairo-scaled-font-t>) ⇒ (ret <cairo-font-type-t>)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’.
a <cairo-scaled-font-t>
The type of scaled-font.
Since 1.2
Next: Font Options, Previous: Font Faces, Up: Top [Index]