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 1024, 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;

A PangoGlyph represents a single glyph in the output form of a string.

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.

PangoGlyphUnit

typedef gint32 PangoGlyphUnit;

The PangoGlyphUnit type is used to store dimensions within Pango. Dimensions are stored in 1/PANGO_SCALE of a device unit. (A device unit might be a pixel for screen display, or a point on a printer.) PANGO_SCALE is currently 1024, and is unlikely to change, but you should not depend on its exact value. The PANGO_PIXELS() macro can be used to convert from glyph units into device units with correct rounding.

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;

};

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.

struct PangoGlyphItem

struct PangoGlyphItem {

  PangoItem        *item;
  PangoGlyphString *glyphs;
};

A PangoGlyphItem is a pair of a PangoItem and the glyphs resulting from shaping the text corresponding to an item. As an example of the usage of PangoGlyphItem, the results of shaping text with PangoLayout is a list of PangoLayoutLine, each of which contains a list of PangoGlyphItem.

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.

pango_glyph_item_split ()

PangoGlyphItem* pango_glyph_item_split      (PangoGlyphItem *orig,
                                             const char *text,
                                             int split_index);

Modifies orig to cover only the text after split_index, and returns a new item that covers the text before split_index that used to be in orig. You can think of split_index as the length of the returned item. split_index may not be 0, and it may not be greater than or equal to the length of orig (that is, there must be at least one byte assigned to each item, you can't create a zero-length item).

This function is similar in function to pango_item_split() (and uses it internally)

pango_glyph_item_apply_attrs ()

GSList*     pango_glyph_item_apply_attrs    (PangoGlyphItem *glyph_item,
                                             const char *text,
                                             PangoAttrList *list);

Splits a shaped item (PangoGlyphItem) into multiple items based on an attribute list. The idea is that if you have attributes that don't affect shaping, such as color or underline, to avoid affecting shaping, you filter them out (pango_attr_list_filter()), apply the shaping process and then reapply them to the result using this function.

All attributes that start or end inside a cluster are applied to that cluster; for instance, if half of a cluster is underlined and the other-half strikethough, then the cluster will end up with both underline and strikethrough attributes. In these cases, it may happen that item->extra_attrs for some of the result items can have multiple attributes of the same type.

This function takes ownership of glyph_item; it will be reused as one of the elements in the list.