Next: , Previous: Layout Objects, Up: Top


6 Rendering

Functions to run the rendering pipeline

6.1 Overview

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.

6.2 Usage

— Class: <pango-context>

Derives from <gobject>.

This class defines no direct slots.

— Class: <pango-item>

Derives from <gboxed>.

This class defines no direct slots.

— Function: pango-itemize (context <pango-context>) (text mchars) (start_index int) (length int) (attrs <pango-attr-list>) (cached_iter <pango-attr-iterator>) ⇒  (ret glist-of)

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 ‘#f
ret
a <g-list> of <pango-item> structures.
— Function: pango-itemize-with-base-dir (context <pango-context>) (base_dir <pango-direction>) (text mchars) (start_index int) (length int) (attrs <pango-attr-list>) (cached_iter <pango-attr-iterator>) ⇒  (ret glist-of)

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 <pango-context>.

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 ‘#f
ret
a <g-list> of <pango-item> structures.

Since 1.4

— Function: pango-item-copy (self <pango-item>) ⇒  (ret <pango-item>)

Copy an existing <pango-item> structure.

item
a <pango-item>
ret
the newly allocated <pango-item>, which should be freed with pango-item-free.
— Function: pango-item-new ⇒  (ret <pango-item>)

Creates a new <pango-item> structure initialized to default values.

ret
the newly allocated <pango-item>, which should be freed with pango-item-free.
— Function: pango-item-split (self <pango-item>) (split_index int) (split_offset int) ⇒  (ret <pango-item>)

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.

orig
a <pango-item>
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
ret
new item representing text before split-index, which should be freed with pango-item-free.
— Function: pango-reorder-items (logical_items glist-of) ⇒  (ret glist-of)

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

logical-items
a <g-list> of <pango-item> in logical order.
ret
a <g-list> of <pango-item> 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.)
— Function: pango-context-get-font-map (self <pango-context>) ⇒  (ret <pango-font-map>)
— Method: get-font-map

Gets the <pango-fontmap> used to look up fonts for this context.

context
a <pango-context>
ret
the font map for the <pango-context>. This value is owned by Pango and should not be unreferenced.

Since 1.6

— Function: pango-context-set-font-description (self <pango-context>) (desc <pango-font-description>)
— Method: set-font-description

Set the default font description for the context

context
a <pango-context>
desc
the new pango font description
— Function: pango-context-get-language (self <pango-context>) ⇒  (ret <pango-language>)
— Method: get-language

Retrieves the global language tag for the context.

context
a <pango-context>
ret
the global language tag.
— Function: pango-context-set-language (self <pango-context>) (language <pango-language>)
— Method: set-language

Sets the global language tag for the context.

context
a <pango-context>
language
the new language tag.
— Function: pango-context-get-base-dir (self <pango-context>) ⇒  (ret <pango-direction>)
— Method: get-base-dir

Retrieves the base direction for the context. See pango-context-set-base-dir.

context
a <pango-context>
ret
the base direction for the context.
— Function: pango-context-set-base-dir (self <pango-context>) (direction <pango-direction>)
— Method: set-base-dir

Sets the base direction for the context.

The base direction is used in applying the Unicode bidirectional algorithm; if the direction is ‘PANGO_DIRECTION_LTR’ or ‘PANGO_DIRECTION_RTL’, then the value will be used as the paragraph direction in the Unicode bidirectional algorithm. A value of ‘PANGO_DIRECTION_WEAK_LTR’ or ‘PANGO_DIRECTION_WEAK_RTL’ is used only for paragraphs that do not contain any strong characters themselves.

context
a <pango-context>
direction
the new base direction
— Function: pango-context-get-matrix (self <pango-context>) ⇒  (ret <pango-matrix>)
— Method: get-matrix

Gets the transformation matrix that will be applied when rendering with this context. See pango-context-set-matrix.

context
a <pango-context>
ret
the matrix, or ‘#f’ if no matrix has been set (which is the same as the identity matrix). The returned matrix is owned by Pango and must not be modified or freed.

Since 1.6

— Function: pango-context-set-matrix (self <pango-context>) (matrix <pango-matrix>)
— Method: set-matrix

Sets the transformation matrix that will be applied when rendering with this context. Note that reported metrics are in the user space coordinates before the application of the matrix, not device-space coordinates after the application of the matrix. So, they don't scale with the matrix, though they may change slightly for different matrices, depending on how the text is fit to the pixel grid.

context
a <pango-context>
matrix
a <pango-matrix>, or ‘#f’ to unset any existing matrix. (No matrix set is the same as setting the identity matrix.)

Since 1.6

— Function: pango-context-load-font (self <pango-context>) (desc <pango-font-description>) ⇒  (ret <pango-font>)
— Method: load-font

Loads the font in one of the fontmaps in the context that is the closest match for desc.

context
a <pango-context>
desc
a <pango-font-description> describing the font to load
ret
the font loaded, or ‘#f’ if no font matched.
— Function: pango-context-load-fontset (self <pango-context>) (desc <pango-font-description>) (language <pango-language>) ⇒  (ret <pango-fontset>)
— Method: load-fontset

Load a set of fonts in the context that can be used to render a font matching desc.

context
a <pango-context>
desc
a <pango-font-description> describing the fonts to load
language
a <pango-language> the fonts will be used for
ret
the fontset, or ‘#f’ if no font matched.
— Function: pango-context-get-metrics (self <pango-context>) (desc <pango-font-description>) (language <pango-language>) ⇒  (ret <pango-font-metrics>)
— Method: get-metrics

Get overall metric information for a particular font description. Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language.

The <pango-font-description> is interpreted in the same way as by pango-itemize, and the family name may be a comma separated list of figures. If characters from multiple of these families would be used to render the string, then the returned fonts would be a composite of the metrics for the fonts loaded for the individual families.

context
a <pango-context>
desc
a <pango-font-description> structure
language
language tag used to determine which script to get the metrics for. ‘#f’ means that the language tag from the context will be used. If no language tag is set on the context, metrics large enough to cover a range of languages will be returned. The process of determining such metrics is slow, so it is best to always make sure some real language tag will be used.
ret
a <pango-font-metrics> object. The caller must call pango-font-metrics-unref when finished using the object.
— Function: pango-get-mirror-char (ch unsigned-int32) ⇒  (ret bool) (mirrored_ch unsigned-int32)

pango_get_mirror_char’ is deprecated and should not be used in newly-written code.

If ch has the Unicode mirrored property and there is another Unicode character that typically has a glyph that is the mirror image of ch's glyph, puts that character in the address pointed to by mirrored-ch.

Use g-unichar-get-mirror-char instead; the docs for that function provide full details.

ch
a Unicode character
mirrored-ch
location to store the mirrored character
ret
#t’ if ch has a mirrored character and mirrored-ch is filled in, ‘#f’ otherwise
— Function: pango-unichar-direction (ch unsigned-int32) ⇒  (ret <pango-direction>)

Determines the direction of a character; either ‘PANGO_DIRECTION_LTR’, ‘PANGO_DIRECTION_RTL’, or ‘PANGO_DIRECTION_NEUTRAL’.

ch
a Unicode character
ret
the direction of the character, as used in the Unicode bidirectional algorithm.
— Function: pango-find-base-dir (text mchars) (length int) ⇒  (ret <pango-direction>)

Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.

text
the text to process
length
length of text in bytes (may be -1 if text is nul-terminated)
ret
The direction corresponding to the first strong character. If no such character is found, then ‘PANGO_DIRECTION_NEUTRAL’ is returned.

Since 1.4

— Function: pango-find-paragraph-boundary (text mchars) (length int) ⇒  (paragraph_delimiter_index int) (next_paragraph_start int)

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

text
UTF-8 text
length
length of text in bytes, or -1 if nul-terminated
paragraph-delimiter-index
return location for index of delimiter
next-paragraph-start
return location for start of next paragraph