cairo2 0.5 · OCaml Package

This is Cairo low-level text API. The low-level API relies on the user to convert text to a set of glyph indexes and positions. This is a very hard problem and is best handled by external libraries, like the pangocairo that is part of the Pango text layout and rendering library. Pango is available from http://www.pango.org/

See also the "Toy" text API.

type t = {

index : int;
(*
glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
*)
x : float;
(*
the offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph.
*)
y : float;
(*
the offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph.
*)

}

The Glyph.t structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.

Note that the offsets given by x and y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin.

type cluster = {

num_bytes : int;
(*
the number of bytes of UTF-8 text covered by cluster
*)
num_glyphs : int;
(*
the number of glyphs covered by cluster
*)

}

The cluster record holds information about a single text cluster. A text cluster is a minimal mapping of some glyphs corresponding to some UTF-8 text.

For a cluster to be valid, both num_bytes and num_glyphs should be non-negative, and at least one should be non-zero. Note that clusters with zero glyphs are not as well supported as normal clusters. For example, PDF rendering applications typically ignore those clusters when PDF text is being selected.

See Cairo.Glyph.show_text for how clusters are used in advanced text operations.

type cluster_flags =

| BACKWARD
(*
The clusters in the cluster array map to glyphs in the glyph array from end to start.
*)

Specifies properties of a text cluster mapping.

val extents : context -> t array -> text_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.Glyph.show). 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 show : context -> t array -> unit

A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.

val show_text : 
  context ->
  string ->
  t array ->
  cluster array ->
  cluster_flags ->
  unit

show_text cr utf8 glyphs clusters cluster_flags: This operation has rendering effects similar to Cairo.Glyph.show but, if the target surface supports it, uses the provided text and cluster mapping to embed the text for the glyphs shown in the output. If the target does not support the extended attributes, this function acts like the basic Cairo.Glyph.show as if it had been passed glyphs.

The mapping between utf8 and glyphs is provided by an array of clusters. Each cluster covers a number of text bytes and glyphs, and neighboring clusters cover neighboring areas of utf8 and glyphs. The clusters should collectively cover utf8 and glyphs in entirety.

The first cluster always covers bytes from the beginning of utf8. If cluster_flags do not have the BACKWARD set, the first cluster also covers the beginning of glyphs, otherwise it covers the end of the glyphs array and following clusters move backward.

See Cairo.Glyph.cluster for constraints on valid clusters.

package cairo2