Rendering: Pango Reference Manual

## Rendering Rendering — Functions to run the rendering pipeline |

## Functions

GList * | pango_itemize ()
GList * | pango_itemize_with_base_dir ()
void | pango_item_free ()
PangoItem * | pango_item_copy ()
PangoItem * | pango_item_new ()
PangoItem * | pango_item_split ()
void | pango_item_apply_attrs ()
GList * | pango_reorder_items ()
void | pango_break ()
void | pango_get_log_attrs ()
void | pango_find_paragraph_boundary ()
void | pango_default_break ()
void | pango_tailor_break ()
void | pango_shape ()
void | pango_shape_full ()
void | pango_shape_with_flags ()

## Types and Values

struct | PangoItem
struct | PangoAnalysis
#define | PANGO_ANALYSIS_FLAG_CENTERED_BASELINE
#define | PANGO_ANALYSIS_FLAG_IS_ELLIPSIS
#define | PANGO_ANALYSIS_FLAG_NEED_HYPHEN
| PangoLogAttr
enum | PangoShapeFlags

## Object Hierarchy

        GBoxed
        ╰── PangoItem
        GFlags
        ╰── PangoShapeFlags

## 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.

## Functions

### 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` ).

#### Parameters

context | a structure holding information that affects the itemization process. |
text | the text to itemize. Must be valid UTF-8 |
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`. | [allow-none]

#### 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()`.

[transfer full][element-type Pango.Item]

### 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.

#### Parameters

context | a structure holding information that affects the itemization process. |
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`. | [allow-none]

#### 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()`.

[transfer full][element-type Pango.Item]

Since: 1.4

### pango_item_free ()

    void
    pango_item_free (PangoItem *item);

Free a PangoItem and all associated memory.

#### Parameters

item | a PangoItem, may be `NULL`. | [nullable]

### pango_item_copy ()

    PangoItem *
    pango_item_copy (PangoItem *item);

Copy an existing PangoItem structure.

#### Parameters

item | a PangoItem, may be `NULL`. | [nullable]

#### Returns

the newly allocated PangoItem, which should be freed with `pango_item_free()`, or `NULL` if `item` was `NULL`.

[nullable]

### 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 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). `split_offset` is the length of the first item in chars, and must be provided because the text used to generate the item isn't available, so `pango_item_split()` can't count the char length of the split items itself.

#### Parameters

orig | a PangoItem |
split_index | byte index of position to split item, relative to the start of the item |
split_offset | number of chars between start of `orig` and `split_index` |

#### Returns

new item representing text before `split_index` , which should be freed with `pango_item_free()`.

### pango_item_apply_attrs ()

    void
    pango_item_apply_attrs (PangoItem *item,
                            PangoAttrIterator *iter);

Add attributes to a PangoItem. The idea is that you have attributes that don't affect itemization, such as font features, so you filter them out using `pango_attr_list_filter()`, itemize your text, then reapply the attributes to the resulting items using this function.

The `iter` should be positioned before the range of the item, and will be advanced past it. This function is meant to be called in a loop over the items resulting from itemization, while passing the iter to each call.

#### Parameters

item | a PangoItem |
iter | a PangoAttrIterator |

Since: 1.44

### pango_reorder_items ()

    GList *
    pango_reorder_items (GList *logical_items);

From a list of items in logical order and the associated directional levels, produce a list in visual order. The original list is unmodified.

#### Parameters

logical_items | a GList of PangoItem in logical order. | [element-type Pango.Item]

#### Returns

a GList of PangoItem structures in visual order.

(Please open a bug if you use this function. It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.).

[transfer full][element-type Pango.Item]

### pango_break ()

    void
    pango_break (const gchar *text,
                 int length,
                 PangoAnalysis *analysis,
                 PangoLogAttr *attrs,
                 int attrs_len);

`pango_break` has been deprecated since version 1.44 and should not be used in newly-written code.

Use `pango_default_break()` and `pango_tailor_break()`

Determines possible line, word, and character breaks for a string of Unicode text with a single analysis. For most purposes you may want to use `pango_get_log_attrs()`.

#### Parameters

text | the text to process. Must be valid UTF-8 |
length | length of `text` in bytes (may be -1 if `text` is nul-terminated) |
analysis | PangoAnalysis structure from `pango_itemize()` |
attrs | an array to store character information in. | [array length=attrs_len]
attrs_len | size of the array passed as `attrs` |

### pango_get_log_attrs ()

    void
    pango_get_log_attrs (const char *text,
                         int length,
                         int level,
                         PangoLanguage *language,
                         PangoLogAttr *log_attrs,
                         int attrs_len);

Computes a PangoLogAttr for each character in `text` . The `log_attrs` array must have one PangoLogAttr for each position in `text` ; if `text` contains N characters, it has N+1 positions, including the last position at the end of the text. `text` should be an entire paragraph; logical attributes can't be computed without context (for example you need to see spaces on either side of a word to know the word is a word).

#### Parameters

text | text to process. Must be valid UTF-8 |
length | length in bytes of `text` |
level | embedding level, or -1 if unknown |
language | language tag |
log_attrs | array with one PangoLogAttr per character in `text` , plus one extra, to be filled in. | [array length=attrs_len]
attrs_len | length of `log_attrs` array |

### pango_find_paragraph_boundary ()

    void
    pango_find_paragraph_boundary (const gchar *text,
                                   gint length,
                                   gint *paragraph_delimiter_index,
                                   gint *next_paragraph_start);

Locates a paragraph boundary in `text` . A boundary is caused by delimiter characters, such as a newline, carriage return, carriage return-newline pair, or Unicode paragraph separator character. The index of the run of delimiters is returned in `paragraph_delimiter_index` . The index of the start of the paragraph (index after all delimiters) is stored in `next_paragraph_start` .

If no delimiters are found, both `paragraph_delimiter_index` and `next_paragraph_start` are filled with the length of `text` (an index one off the end).

#### Parameters

text | UTF-8 text |
length | length of `text` in bytes, or -1 if nul-terminated |
paragraph_delimiter_index | return location for index of delimiter. | [out]
next_paragraph_start | return location for start of next paragraph. | [out]

### pango_default_break ()

    void
    pango_default_break (const gchar *text,
                         int length,
                         PangoAnalysis *analysis,
                         PangoLogAttr *attrs,
                         int attrs_len);

This is the default break algorithm. It applies Unicode rules without language-specific tailoring, therefore the `analyis` argument is unused and can be `NULL`.

See `pango_tailor_break()` for language-specific breaks.

#### Parameters

text | text to break. Must be valid UTF-8 |
length | length of text in bytes (may be -1 if `text` is nul-terminated) |
analysis | a PangoAnalysis for the `text` . | [nullable]
attrs | logical attributes to fill in |
attrs_len | size of the array passed as `attrs` |

### pango_tailor_break ()

    void
    pango_tailor_break (const char *text,
                        int length,
                        PangoAnalysis *analysis,
                        int offset,
                        PangoLogAttr *log_attrs,
                        int log_attrs_len);

Apply language-specific tailoring to the breaks in `log_attrs` , which are assumed to have been produced by `pango_default_break()`.

If `offset` is not -1, it is used to apply attributes from `analysis` that are relevant to line breaking.

#### Parameters

text | text to process. Must be valid UTF-8 |
length | length in bytes of `text` |
analysis | PangoAnalysis structure from `pango_itemize()` for `text` |
offset | Byte offset of `text` from the beginning of the paragraph, or -1 to ignore attributes from `analysis` |
log_attrs | array with one PangoLogAttr per character in `text` , plus one extra, to be filled in. | [array length=log_attrs_len]
log_attrs_len | length of `log_attrs` array |

Since: 1.44

### pango_shape ()

    void
    pango_shape (const char *text,
                 int length,
                 const PangoAnalysis *analysis,
                 PangoGlyphString *glyphs);

Given a segment of text and the corresponding PangoAnalysis structure returned from `pango_itemize()`, convert the characters into glyphs. You may also pass in only a substring of the item from `pango_itemize()`.

It is recommended that you use `pango_shape_full()` instead, since that API allows for shaping interaction happening across text item boundaries.

#### Parameters

text | the text to process |
length | the length (in bytes) of `text` |
analysis | PangoAnalysis structure from `pango_itemize()` |
glyphs | glyph string in which to store results |

### pango_shape_full ()

    void
    pango_shape_full (const char *item_text,
                      int item_length,
                      const char *paragraph_text,
                      int paragraph_length,
                      const PangoAnalysis *analysis,
                      PangoGlyphString *glyphs);

Given a segment of text and the corresponding PangoAnalysis structure returned from `pango_itemize()`, convert the characters into glyphs. You may also pass in only a substring of the item from `pango_itemize()`.

This is similar to `pango_shape()`, except it also can optionally take the full paragraph text as input, which will then be used to perform certain cross-item shaping interactions. If you have access to the broader text of which `item_text` is part of, provide the broader text as `paragraph_text` . If `paragraph_text` is `NULL`, item text is used instead.

#### Parameters

item_text | valid UTF-8 text to shape. |
item_length | the length (in bytes) of `item_text` . -1 means nul-terminated text. |
paragraph_text | text of the paragraph (see details). May be `NULL`. | [allow-none]
paragraph_length | the length (in bytes) of `paragraph_text` . -1 means nul-terminated text. |
analysis | PangoAnalysis structure from `pango_itemize()`. |
glyphs | glyph string in which to store results. |

Since: 1.32

### pango_shape_with_flags ()

    void
    pango_shape_with_flags (const char *item_text,
                            int item_length,
                            const char *paragraph_text,
                            int paragraph_length,
                            const PangoAnalysis *analysis,
                            PangoGlyphString *glyphs,
                            PangoShapeFlags flags);

Given a segment of text and the corresponding PangoAnalysis structure returned from `pango_itemize()`, convert the characters into glyphs. You may also pass in only a substring of the item from `pango_itemize()`.

This is similar to `pango_shape_full()`, except it also takes flags that can influence the shaping process.

#### Parameters

item_text | valid UTF-8 text to shape |
item_length | the length (in bytes) of `item_text` . -1 means nul-terminated text. |
paragraph_text | text of the paragraph (see details). May be `NULL`. | [allow-none]
paragraph_length | the length (in bytes) of `paragraph_text` . -1 means nul-terminated text. |
analysis | PangoAnalysis structure from `pango_itemize()` |
glyphs | glyph string in which to store results |
flags | flags influencing the shaping process |

Since: 1.44

## Types and Values

### struct PangoItem

    struct PangoItem {
      gint offset;
      gint length;
      gint num_chars;
      PangoAnalysis analysis;
    };

The PangoItem structure stores information about a segment of text.

#### Members

gint `offset`; | byte offset of the start of this item in text. |
gint `length`; | length of this item in bytes. |
gint `num_chars`; | number of Unicode characters in the item. |
PangoAnalysis `analysis`; | analysis results for the item. |

### struct PangoAnalysis

    struct PangoAnalysis {
      PangoEngineShape *shape_engine;
      PangoEngineLang  *lang_engine;
      PangoFont *font;

      guint8 level;
      guint8 gravity;
      guint8 flags;

      guint8 script;
      PangoLanguage *language;

      GSList *extra_attrs;
    };

The PangoAnalysis structure stores information about the properties of a segment of text.

#### Members

PangoEngineShape *`shape_engine`; | unused |
PangoEngineLang *`lang_engine`; | unused |
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 (Since: 1.16). |
guint8 `script`; | the detected script for this segment (A PangoScript) (Since: 1.18). |
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 directions mostly.

Since: 1.16

### PANGO_ANALYSIS_FLAG_IS_ELLIPSIS

    #define PANGO_ANALYSIS_FLAG_IS_ELLIPSIS (1 << 1)

This flag is used to mark runs that hold ellipsized text, in an ellipsized layout.

Since: 1.36.7

### PANGO_ANALYSIS_FLAG_NEED_HYPHEN

    #define PANGO_ANALYSIS_FLAG_NEED_HYPHEN (1 << 2)

This flag tells Pango to add a hyphen at the end of the run during shaping.

Since: 1.44

### PangoLogAttr

    typedef struct {
      guint is_line_break               : 1;
      guint is_mandatory_break          : 1;
      guint is_char_break               : 1;
      guint is_white                    : 1;
      guint is_cursor_position          : 1;
      guint is_word_start               : 1;
      guint is_word_end                 : 1;
      guint is_sentence_boundary        : 1;
      guint is_sentence_start           : 1;
      guint is_sentence_end             : 1;
      guint backspace_deletes_character : 1;
      guint is_expandable_space         : 1;
      guint is_word_boundary            : 1;
    } PangoLogAttr;

The PangoLogAttr structure stores information about the attributes of a single character.

#### Members

guint `is_line_break` : 1; | if set, can break line in front of character |
guint `is_mandatory_break` : 1; | if set, must break line in front of character |
guint `is_char_break` : 1; | if set, can break here when doing character wrapping |
guint `is_white` : 1; | is whitespace character |
guint `is_cursor_position` : 1; | if set, cursor can appear in front of character. i.e. this is a grapheme boundary, or the first character in the text. This flag implements Unicode's Grapheme Cluster Boundaries semantics. |
guint `is_word_start` : 1; | is first character in a word |
guint `is_word_end` : 1; | is first non-word char after a word Note that in degenerate cases, you could have both `is_word_start` and `is_word_end` set for some character. |
guint `is_sentence_boundary` : 1; | is a sentence boundary. There are two ways to divide sentences. The first assigns all inter-sentence whitespace/control/format chars to some sentence, so all chars are in some sentence; `is_sentence_boundary` denotes the boundaries there. The second way doesn't assign between-sentence spaces, etc. to any sentence, so `is_sentence_start` /`is_sentence_end` mark the boundaries of those sentences. |
guint `is_sentence_start` : 1; | is first character in a sentence |
guint `is_sentence_end` : 1; | is first char after a sentence. Note that in degenerate cases, you could have both `is_sentence_start` and `is_sentence_end` set for some character. (e.g. no space after a period, so the next sentence starts right away) |
guint `backspace_deletes_character` : 1; | if set, backspace deletes one character rather than the entire grapheme cluster. This field is only meaningful on grapheme boundaries (where `is_cursor_position` is set). In some languages, the full grapheme (e.g. letter + diacritics) is considered a unit, while in others, each decomposed character in the grapheme is a unit. In the default implementation of `pango_break()`, this bit is set on all grapheme boundaries except those following Latin, Cyrillic or Greek base characters. |
guint `is_expandable_space` : 1; | is a whitespace character that can possibly be expanded for justification purposes. (Since: 1.18) |
guint `is_word_boundary` : 1; | is a word boundary, as defined by UAX29. More specifically, means that this is not a position in the middle of a word. For example, both sides of a punctuation mark are considered word boundaries. This flag is particularly useful when selecting text word-by-word. This flag implements Unicode's Word Boundaries semantics. (Since: 1.22) |

### enum PangoShapeFlags

Flags influencing the shaping process. These can be passed to `pango_shape_with_flags()`.

#### Members

PANGO_SHAPE_NONE | Default value. |
PANGO_SHAPE_ROUND_POSITIONS | Round glyph positions and widths to whole device units. This option should be set if the target renderer can't do subpixel positioning of glyphs. |