Module Cairo.Scaled_font

Cairo.Scaled_font.t represents a realization of a font face at a particular size and transformation and a certain set of font options.

type 'a t

A Cairo.Scaled_font.t is a font scaled to a particular size and device resolution. It 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.

val set : context -> _ t -> unit

Replaces the current font face, font matrix, and font options in the Cairo.context with those of the Cairo.Scaled_font.t. Except for some translation, the current CTM of the Cairo.context should be the same as that of the Cairo.Scaled_font.t, which can be accessed using Cairo.Scaled_font.get_ctm.

val get : context -> 'a t

Gets the current scaled font for a cairo_t.

val create : 'a Font_face.t -> Matrix.t -> Matrix.t -> Font_options.t -> 'a t

create font_face font_matrix ctm 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.

val extents : _ t -> font_extents

extents sf gets the metrics for sf.

val text_extents : _ t -> string -> text_extents

text_extents scaled_font utf8 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. The string utf8 should not contain '\000' characters.

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.

val glyph_extents : _ t -> Glyph.t array -> text_extents

glyph_extents scaled_font glyphs 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.Glyph.show 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.Glyph.show.

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

val text_to_glyphs : _ t -> x:float -> y:float -> string -> Glyph.t array * Glyph.cluster array * Glyph.cluster_flags

text_to_glyphs scaled_font x y utf8 converts UTF-8 text to an array of glyphs, optionally with cluster mapping, that can be used to render later using scaled_font. See Cairo.Glyph.show_text.

val get_font_face : 'a t -> 'a Font_face.t

Gets the font face that this scaled font was created for.

val get_font_options : _ t -> Font_options.t

get_font_options scaled_font returns the font options with which scaled_font was created.

val get_font_matrix : _ t -> Matrix.t

get_font_matrix scaled_font return the font matrix with which scaled_font was created.

val get_ctm : _ t -> Matrix.t

get_ctm scaled_font returns the CTM with which scaled_font was created.

val get_scale_matrix : _ t -> Matrix.t

get_scale_matrix scaled_font returns the scale matrix of scaled_font. 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.

val get_type : 'a t -> font_type

This function returns the type of the backend used to create a scaled font. See Cairo.font_type for available types.