Glyph Storage

PANGO_SCALE

#define PANGO_SCALE 1024

The PANGO_SCALE macro represents the scale between dimensions used for Pango distances and device units. (The definition of device units is dependent on the output device; it will typically be pixels for a screen, and points for a printer.) PANGO_SCALE is currently 1000, but this may be changed in the future.

When setting font sizes, device units are always considered to be points (as in "12 point font"), rather than pixels.

PANGO_PIXELS()

#define     PANGO_PIXELS(d)

Converts a dimension to device units.

struct PangoRectangle

struct PangoRectangle
{
  int x;
  int y;
  int width;
  int height;
};

The PangoRectangle structure represents a rectangle. It is frequently used to represent the logical or ink extents of a single glyph or section of text. (See, for instance, pango_font_get_glyph_extents())

PANGO_ASCENT()

#define PANGO_ASCENT(rect) (-(rect).y)

Extracts the ascent from a PangoRectangle representing glyph extents. The ascent is the distance from the baseline to the highest point of the character. This is positive if the glyph ascends above the baseline.

PANGO_DESCENT()

#define PANGO_DESCENT(rect) ((rect).y + (rect).height)

Extracts the descent from a PangoRectangle representing glyph extents. The descent is the distance from the baseline to the lowest point of the character. This is positive if the glyph descends below the baseline.

PANGO_LBEARING()

#define PANGO_LBEARING(rect) ((rect).x)

Extracts the left bearing from a PangoRectangle representing glyph extents. The left bearing is the distance from the horizontal origin to the farthest left point of the character. This is positive for characters drawn completely to the right of the glyph origin.

PANGO_RBEARING()

#define PANGO_RBEARING(rect) ((rect).x + (rect).width)

Extracts the right bearing from a PangoRectangle representing glyph extents. The right bearing is the distance from the horizontal origin to the farthest right point of the character. This is positive except for characters drawn completely to the left of the horizontal origin.

PangoGlyph

typedef guint32 PangoGlyph;

The PangoGlyph structure represents a single glyph in the output form of a string. It contains the following fields.

struct PangoGlyphInfo

struct PangoGlyphInfo
{
  PangoGlyph    glyph;
  PangoGlyphGeometry geometry;
  PangoGlyphVisAttr  attr;
};

The PangoGlyphInfo structure represents a single glyph together with positioning information and visual attributes. It contains the following fields.

struct PangoGlyphGeometry

struct PangoGlyphGeometry
{
  PangoGlyphUnit width;
  PangoGlyphUnit x_offset;  
  PangoGlyphUnit y_offset;
};

The PangoGlyphGeometry structure contains width and positioning information for a single glyph. Distances are in 1/64ths of a point.

PangoGlyphUnit

typedef gint32 PangoGlyphUnit;

The PangoGlyphUnit type is used to store dimensions within Pango. Dimensions are stored in 1/64ths of a point.

struct PangoGlyphVisAttr

struct PangoGlyphVisAttr
{
  guint is_cluster_start : 1;
};

The PangoGlyphVisAttr is used to communicate information between the shaping phase and the rendering phase. It's contents are still evolving.

struct PangoGlyphString

struct PangoGlyphString {
  gint num_glyphs;

  PangoGlyphInfo *glyphs;

  /* This is a memory inefficient way of representing the information
   * here - each value gives the byte index within the text
   * corresponding to the glyph string of the start of the cluster to
   * which the glyph belongs.
   */
  gint *log_clusters;

  /*< private >*/
  gint space;
};

The PangoGlyphString structure is used to store strings of glyphs with geometry and visual attribute information. The storage for the glyph information is owned by the structure which simplifies memory management.

PangoGlyphString contains the following publically accessible fields

PANGO_TYPE_GLYPH_STRING

#define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())

The GObject type for PangoGlyphString.

pango_glyph_string_new ()

PangoGlyphString* pango_glyph_string_new    (void);

Create a new PangoGlyphString.

pango_glyph_string_copy ()

PangoGlyphString* pango_glyph_string_copy   (PangoGlyphString *string);

Copy a glyph string and associated storage.

pango_glyph_string_set_size ()

void        pango_glyph_string_set_size     (PangoGlyphString *string,
                                             gint new_len);

Resize a glyph string to the given length.

pango_glyph_string_free ()

void        pango_glyph_string_free         (PangoGlyphString *string);

Free a glyph string and associated storage.

pango_glyph_string_extents ()

void        pango_glyph_string_extents      (PangoGlyphString *glyphs,
                                             PangoFont *font,
                                             PangoRectangle *ink_rect,
                                             PangoRectangle *logical_rect);

Compute the logical and ink extents of a glyph string. See the documentation for pango_font_get_glyph_extents() for details about the interpretation of the rectangles.

pango_glyph_string_extents_range ()

void        pango_glyph_string_extents_range
                                            (PangoGlyphString *glyphs,
                                             int start,
                                             int end,
                                             PangoFont *font,
                                             PangoRectangle *ink_rect,
                                             PangoRectangle *logical_rect);

Computes the extents of a sub-portion of a glyph string. The extents are relative to the start of the glyph string range (the origin of their coordinate system is at the start of the range, not at the start of the entire glyph string).

pango_glyph_string_index_to_x ()

void        pango_glyph_string_index_to_x   (PangoGlyphString *glyphs,
                                             char *text,
                                             int length,
                                             PangoAnalysis *analysis,
                                             int index,
                                             gboolean trailing,
                                             int *x_pos);

Converts from character position to x position. (X position is measured from the left edge of the run). Character positions are computed by dividing up each cluster into equal portions.

pango_glyph_string_x_to_index ()

void        pango_glyph_string_x_to_index   (PangoGlyphString *glyphs,
                                             char *text,
                                             int length,
                                             PangoAnalysis *analysis,
                                             int x_pos,
                                             int *index,
                                             int *trailing);

Convert from x offset to character position. Character positions are computed by dividing up each cluster into equal portions. In scripts where positioning within a cluster is not allowed (such as Thai), the returned value may not be a valid cursor position; the caller must combine the result with the logical attributes for the text to compute the valid cursor position.

pango_glyph_string_get_logical_widths ()

void        pango_glyph_string_get_logical_widths
                                            (PangoGlyphString *glyphs,
                                             const char *text,
                                             int length,
                                             int embedding_level,
                                             int *logical_widths);

Given a PangoGlyphString resulting from pango_shape() and the corresponding text, determine the screen width corresponding to each character. When multiple characters compose a single cluster, the width of the entire cluster is divided equally among the characters.