Pango Reference Manual May 17, 2009 Pango Reference Manual ii Contents 1 Basic Pango Interfaces 1 1.1 Rendering . .1 1.2 Glyph Storage . 13 1.3 Fonts . 32 1.4 Text Attributes . 59 1.5 Tab Stops . 79 1.6 Text Attribute Markup . 83 1.7 Layout Objects . 85 1.8 Scripts and Languages . 109 1.9 Bidirectional Text . 118 1.10 Vertical Text . 121 2 Rendering with Pango 125 2.1 Win32 Fonts and Rendering . 125 2.2 FreeType Fonts and Rendering . 132 2.3 Xft Fonts and Rendering . 140 2.4 Cairo Rendering . 149 2.5 ATSUI Fonts . 161 2.6 Deprecated X font backend . 162 3 Low Level Functionality 175 3.1 PangoRenderer . 175 3.2 PangoFcFontMap . 183 3.3 PangoFcFont . 190 3.4 PangoFcDecoder . 194 3.5 OpenType Font Handling . 195 3.6 Coverage Maps . 210 3.7 Engines . 213 3.8 PangoEngineLang . 216 3.9 PangoEngineShape . 217 3.10 Modules . 219 3.11 Miscellaneous Utilities . 221 3.12 Version Checking . 226 4 Pango Tools 229 4.1 pango-querymodules . 229 5 Object Hierarchy 231 Index 233 iii List of Figures 1 Basic Pango Interfaces 1.1 Adjustable parameters for a PangoLayout . 88 2 Rendering with Pango 2.1 Output of . 153 v Chapter 1 Basic Pango Interfaces 1.1 Rendering Name Rendering – Functions to run the rendering pipeline Synopsis PangoContext; PangoItem; PangoAnalysis; #define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE #define PANGO_TYPE_DIRECTION GList * pango_itemize (PangoContext *context, const char *text, int start_index, int length, PangoAttrList *attrs, PangoAttrIterator *cached_iter); GList * pango_itemize_with_base_dir (PangoContext *context, PangoDirection base_dir, const char *text, int start_index, int length, PangoAttrList *attrs, PangoAttrIterator *cached_iter); void pango_item_free (PangoItem *item); PangoItem * pango_item_copy (PangoItem *item); PangoItem * pango_item_new (void); PangoItem * pango_item_split (PangoItem *orig, int split_index, int split_offset); GList * pango_reorder_items (GList *logical_items); PangoContext * pango_context_new (void); void pango_context_set_font_map (PangoContext *context, PangoFontMap *font_map); PangoFontMap * pango_context_get_font_map (PangoContext *context); PangoFontDescription * pango_context_get_font_description (PangoContext *context); void pango_context_set_font_description (PangoContext *context, const PangoFontDescription *desc); PangoLanguage * pango_context_get_language (PangoContext *context); 1 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING void pango_context_set_language (PangoContext *context, PangoLanguage *language); PangoDirection pango_context_get_base_dir (PangoContext *context); void pango_context_set_base_dir (PangoContext *context, PangoDirection direction); PangoGravity pango_context_get_base_gravity (PangoContext *context); void pango_context_set_base_gravity (PangoContext *context, PangoGravity gravity); PangoGravity pango_context_get_gravity (PangoContext *context); PangoGravityHint pango_context_get_gravity_hint (PangoContext *context); void pango_context_set_gravity_hint (PangoContext *context, PangoGravityHint hint); const PangoMatrix * pango_context_get_matrix (PangoContext *context); void pango_context_set_matrix (PangoContext *context, const PangoMatrix *matrix); PangoFont * pango_context_load_font (PangoContext *context, const PangoFontDescription *desc); PangoFontset * pango_context_load_fontset (PangoContext *context, const PangoFontDescription *desc, PangoLanguage *language); PangoFontMetrics * pango_context_get_metrics (PangoContext *context, const PangoFontDescription *desc, PangoLanguage *language); void pango_context_list_families (PangoContext *context, PangoFontFamily ***families, int *n_families); void pango_break (const gchar *text, int length, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len); void pango_get_log_attrs (const char *text, int length, int level, PangoLanguage *language, PangoLogAttr *log_attrs, int attrs_len); void pango_find_paragraph_boundary (const gchar *text, gint length, gint *paragraph_delimiter_index, gint *next_paragraph_start); void pango_default_break (const gchar *text, int length, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len); PangoLogAttr; void pango_shape (const gchar *text, gint length, const PangoAnalysis *analysis, PangoGlyphString *glyphs); Object Hierarchy GObject +----PangoContext 2 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING Description The Pango rendering pipeline takes a string of Unicode characters and converts it into glyphs. The functions described in this section accomplish various steps of this process. Details PangoContext typedef struct _PangoContext PangoContext; The PangoContext structure stores global information used to control the itemization process. PangoItem typedef struct{ gint offset; gint length; gint num_chars; PangoAnalysis analysis; } PangoItem; The PangoItem structure stores information about a segment of text. It contains the following fields: gint offset; the offset of the segment from the beginning of the string in bytes. gint length; the length of the segment in bytes. gint num_chars; the length of the segment in characters. PangoAnalysis analysis; the properties of the segment. PangoAnalysis typedef struct{ PangoEngineShape *shape_engine; PangoEngineLang *lang_engine; PangoFont *font; guint8 level; guint8 gravity;/* PangoGravity */ guint8 flags; guint8 script;/* PangoScript */ PangoLanguage *language; GSList *extra_attrs; } PangoAnalysis; The PangoAnalysis structure stores information about the properties of a segment of text. It has the following fields: PangoEngineShape* shape_engine; the engine for doing rendering-system-dependent processing. PangoEngineLang* lang_engine; the engine for doing rendering-system-independent processing. PangoFont* font; the font for this segment. guint8 level; the bidirectional level for this segment. guint8 gravity; the glyph orientation for this segment (A PangoGravity). guint8 flags; boolean flags for this segment (currently only one) (Since: 1.16). guint8 script; the detected script for this segment (A PangoScript) (Since: 1.18). 3 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING PangoLanguage* language; the detected language for this segment. GSList* extra_attrs; extra attributes for this segment. PANGO_ANALYSIS_FLAG_CENTERED_BASELINE #define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE (1 << 0) Whether the segment should be shifted to center around the baseline. Used in vertical writing direc- tions mostly. Since: 1.16 PANGO_TYPE_DIRECTION #define PANGO_TYPE_DIRECTION(pango_direction_get_type()) The GObject type for PangoDirection. pango_itemize () GList * pango_itemize(PangoContext *context, const char *text, int start_index, int length, PangoAttrList *attrs, PangoAttrIterator * - cached_iter); Breaks a piece of text into segments with consistent directional level and shaping engine. Each byte of text will be contained in exactly one of the items in the returned list; the generated list of items will be in logical order (the start offsets of the items are ascending). cached_iter should be an iterator over attrs currently positioned at a range before or containing start_index; cached_iter will be advanced to the range covering the position just after start_index + length. (i.e. if itemizing in a loop, just keep passing in the same cached_iter). context : a structure holding information that affects the itemization process. text : the text to itemize. start_index : first byte in text to process length : the number of bytes (not characters) to process after start_index. This must be >= 0. attrs : the set of attributes that apply to text. cached_iter : Cached attribute iterator, or NULL Returns : a GList of PangoItem structures. pango_itemize_with_base_dir () GList * pango_itemize_with_base_dir(PangoContext *context, PangoDirection base_dir, const char *text, int start_index, int length, PangoAttrList *attrs, PangoAttrIterator * - cached_iter); Like pango_itemize(), but the base direction to use when computing bidirectional levels (see pango_context_set_base_dir()), is specified explicitly rather than gotten from the PangoContext. context : a structure holding information that affects the itemization process. 4 CHAPTER 1. BASIC PANGO INTERFACES 1.1. RENDERING base_dir : base direction to use for bidirectional processing text : the text to itemize. start_index : first byte in text to process length : the number of bytes (not characters) to process after start_index. This must be >= 0. attrs : the set of attributes that apply to text. cached_iter : Cached attribute iterator, or NULL Returns : a GList of PangoItem structures. The items should be freed using pango_item_free() probably in combination with g_list_foreach(), and the list itself using g_list_free(). Since 1.4 pango_item_free () void pango_item_free(PangoItem *item); Free a PangoItem and all associated memory. item : a PangoItem, may be NULL pango_item_copy () PangoItem * pango_item_copy(PangoItem *item); Copy an existing PangoItem structure. item : a PangoItem, may be NULL Returns : the newly allocated PangoItem, which should be freed with pango_item_free(), or NULL if item was NULL. pango_item_new () PangoItem * pango_item_new(void); Creates a new PangoItem structure initialized to default values. Returns : the newly allocated PangoItem, which should be freed with pango_item_free(). pango_item_split () PangoItem * pango_item_split(PangoItem *orig, int split_index, int split_offset); 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