Next: , Previous: Font Faces, Up: Top


8 Scaled Fonts

Font face at particular size and options

8.1 Overview

<cairo-scaled-font> represents a realization of a font face at a particular size and transformation and a certain set of font options.

8.2 Usage

— Function: cairo-scaled-font-create (font-face <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.

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.
ret
a newly created <cairo-scaled-font-t>. Destroy with cairo-scaled-font-destroy
— Function: cairo-scaled-font-extents (scaled-font <cairo-scaled-font-t>) (extents <cairo-font-extents-t>)

Gets the metrics for a <cairo-scaled-font-t>.

scaled-font
a <cairo-scaled-font-t>
extents
a <cairo-font-extents-t> which to store the retrieved extents.
— Function: cairo-scaled-font-text-extents (scaled-font <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.

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

— Function: cairo-scaled-font-glyph-extents (scaled-font <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).

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.
— Function: cairo-scaled-font-text-to-glyphs (scaled-font <cairo-scaled-font-t>) (<double>) (<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.

scaled-font
a <cairo-scaled-font-t>
x
X position to place first glyph
y
Y position to place first glyph
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 ‘#f
num-clusters
pointer to number of clusters, or ‘#f
cluster-flags
pointer to location to store cluster flags corresponding to the output clusters, or ‘#f
ret
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

— Function: cairo-scaled-font-get-font-face (scaled-font <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.

scaled-font
a <cairo-scaled-font-t>
ret
The <cairo-font-face-t> with which scaled-font was created.

Since 1.2

— Function: cairo-scaled-font-get-font-options (scaled-font <cairo-scaled-font-t>) (options <cairo-font-options-t>)

Stores the font options with which scaled-font was created into options.

scaled-font
a <cairo-scaled-font-t>
options
return value for the font options

Since 1.2

— Function: cairo-scaled-font-get-font-matrix (scaled-font <cairo-scaled-font-t>) (font-matrix <cairo-matrix-t>)

Stores the font matrix with which scaled-font was created into matrix.

scaled-font
a <cairo-scaled-font-t>
font-matrix
return value for the matrix

Since 1.2

— Function: cairo-scaled-font-get-ctm (scaled-font <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.

scaled-font
a <cairo-scaled-font-t>
ctm
return value for the CTM

Since 1.2

— Function: cairo-scaled-font-get-type (scaled-font <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’.

scaled-font
a <cairo-scaled-font-t>
ret
The type of scaled-font.

Since 1.2