Rendering

Name

Rendering -- Functions to run the rendering pipeline.

Synopsis




struct      PangoContext;
struct      PangoItem;
struct      PangoAnalysis;
struct      PangoLangRange;
enum        PangoDirection;

GList*      pango_itemize                   (PangoContext *context,
                                             const char *text,
                                             gint length,
                                             PangoAttrList *attrs);
void        pango_item_free                 (PangoItem *item);
PangoItem*  pango_item_copy                 (PangoItem *item);
PangoItem*  pango_item_new                  (void);
GList*      pango_reorder_items             (GList *logical_items);

PangoContext* pango_context_new             (void);
void        pango_context_add_font_map      (PangoContext *context,
                                             PangoFontMap *font_map);
PangoFontDescription* pango_context_get_font_description
                                            (PangoContext *context);
void        pango_context_set_font_description
                                            (PangoContext *context,
                                             const PangoFontDescription *desc);
PangoDirection pango_context_get_base_dir   (PangoContext *context);
void        pango_context_set_base_dir      (PangoContext *context,
                                             PangoDirection direction);
char*       pango_context_get_lang          (PangoContext *context);
void        pango_context_set_lang          (PangoContext *context,
                                             const char *lang);
PangoFont*  pango_context_load_font         (PangoContext *context,
                                             const PangoFontDescription *desc);
void        pango_context_list_families     (PangoContext *context,
                                             gchar ***families,
                                             int *n_families);
void        pango_context_list_fonts        (PangoContext *context,
                                             const char *family,
                                             PangoFontDescription ***descs,
                                             int *n_descs);


void        pango_break                     (const gchar *text,
                                             gint length,
                                             PangoAnalysis *analysis,
                                             PangoLogAttr *attrs);
struct      PangoLogAttr;

void        pango_shape                     (const gchar *text,
                                             gint length,
                                             PangoAnalysis *analysis,
                                             PangoGlyphString *glyphs);
void        pango_justify                   (PangoGlyphString *glyphs,
                                             gint new_line_width,
                                             gint min_kashida_width);

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

struct PangoContext

struct PangoContext;

The PangoContext structure stores global information used to control the itemization process. It contains the following fields:

gchar *lang;the global default language in the standard form "fr" or "fr_FR". (This may be overriden with the lang_info parameter to pango_itemize().)
gchar *render_type;a string identifier for the rendering system to use, for instance PANGO_RENDER_TYPE_X


struct PangoItem

struct PangoItem
{
  gint offset;
  gint length;
  gint num_chars;
  GSList *extra_attrs;
  PangoAnalysis analysis;
};

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.
gint analysis;the properties of the segment.


struct PangoAnalysis

struct PangoAnalysis
{
  PangoEngineShape *shape_engine;
  PangoEngineLang  *lang_engine;
  PangoFont        *font;
  guint8 level;
};

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
guint8 level;the bidrectional level for this segment.


struct PangoLangRange

struct PangoLangRange
{
  gint start;
  gint length;
  gchar *lang;
};

The PangoLangRange structure stores language tagging information for a range of character positions of text. It contains the following fields:

gint start;the start position of this tagged range in bytes.
gint length;the length of this tagged range in bytes.
gchar *lang;the language for this range, in the standard form "fr" or "fr_FR".


enum PangoDirection

typedef enum {
  PANGO_DIRECTION_LTR,
  PANGO_DIRECTION_RTL,
  PANGO_DIRECTION_TTB_LTR,
  PANGO_DIRECTION_TTB_RTL
} PangoDirection;

The PangoDirection type represents the direction of writing for text.

PANGO_DIRECTION_LTRThe text is written left-to-right
PANGO_DIRECTION_RTLThe text is written right-to-left
PANGO_DIRECTION_TTB_LTRThe text is written vertically top-to-bottom, with the rows ordered from left to right.
PANGO_DIRECTION_TTB_RTLThe text is written vertically top-to-bottom, with the rows ordered from right to left.


pango_itemize ()

GList*      pango_itemize                   (PangoContext *context,
                                             const char *text,
                                             gint length,
                                             PangoAttrList *attrs);

Breaks a piece of text into segments with consistent directional level and shaping engine.

context : a structure holding information that affects the itemization process.
text : the text to itemize.
length : the number of bytes (not characters) in text. This must be >= 0.
attrs : the set of attributes that apply to text.
Returns :a GList of PangoItem structures.


pango_item_free ()

void        pango_item_free                 (PangoItem *item);

Free a PangoItem and all associated memory.

item : a PangoItem


pango_item_copy ()

PangoItem*  pango_item_copy                 (PangoItem *item);

Copy an existing PangoItem structure.

item : a PangoItem
Returns : the new PangoItem


pango_item_new ()

PangoItem*  pango_item_new                  (void);

Creates a new PangoItem structure initialized to default values.

Returns : the new PangoItem


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.

logical_items : a GList of PangoItem in logical order.
Returns :a GList of PangoItem structures in visual order. (Please mail otaylorredhat.com if you use this function. It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.)


pango_context_new ()

PangoContext* pango_context_new             (void);

Creates a new PangoContext initialized to default value.

Returns : the new PangoContext


pango_context_add_font_map ()

void        pango_context_add_font_map      (PangoContext *context,
                                             PangoFontMap *font_map);

Add a font map to the list of font maps that are searched for fonts when fonts are looked-up in this context.

context : a PangoContext
font_map : the PangoFontMap to add.


pango_context_get_font_description ()

PangoFontDescription* pango_context_get_font_description
                                            (PangoContext *context);

Retrieve the default font description for the context.

context : a PangoContext
Returns : a pointer to the context's default font description. This value must not be modified or freed.


pango_context_set_font_description ()

void        pango_context_set_font_description
                                            (PangoContext *context,
                                             const PangoFontDescription *desc);

Set the default font description for the context

context : a PangoContext
desc : the new pango font description


pango_context_get_base_dir ()

PangoDirection pango_context_get_base_dir   (PangoContext *context);

Retrieves the base direction for the context.

context : 
Returns : the base direction for the context.


pango_context_set_base_dir ()

void        pango_context_set_base_dir      (PangoContext *context,
                                             PangoDirection direction);

Sets the base direction for the context.

context : a PangoContext
direction : the new base direction


pango_context_get_lang ()

char*       pango_context_get_lang          (PangoContext *context);

Retrieves the global language tag for the context.

context : a PangoContext
Returns : the global language tag. This value must be freed with g_free().


pango_context_set_lang ()

void        pango_context_set_lang          (PangoContext *context,
                                             const char *lang);

Sets the global language tag for the context.

context : a PangoContext
lang : the new language tag.


pango_context_load_font ()

PangoFont*  pango_context_load_font         (PangoContext *context,
                                             const PangoFontDescription *desc);

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

context : a PangoContext
desc : a PangoFontDescription describing the font to load
Returns :the font loaded, or NULL if no font matched.


pango_context_list_families ()

void        pango_context_list_families     (PangoContext *context,
                                             gchar ***families,
                                             int *n_families);

List all families for a context.

context : a PangoContext
families : location to store a pointer to an array of strings. This array should be freed with pango_font_map_free_families().
n_families : location to store the number of elements in descs


pango_context_list_fonts ()

void        pango_context_list_fonts        (PangoContext *context,
                                             const char *family,
                                             PangoFontDescription ***descs,
                                             int *n_descs);

Lists all fonts in all fontmaps for this context, or all fonts in a particular family.

context : a PangoContext
family : the family for which to list the fonts, or NULL to list fonts in all families.
descs : location to store a pointer to an array of pointers to PangoFontDescription. This array should be freed with pango_font_descriptions_free()
n_descs : location to store the number of elements in descs


pango_break ()

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

Determines possible line, word, and character breaks for a string of Unicode text.

text : the text to process
length : the length (in bytes) of text
analysis : PangoAnalysis structure from PangoItemize
attrs : an array to store character information in


struct PangoLogAttr

struct PangoLogAttr
{
  guint is_break : 1;  /* Break in front of character */
  guint is_white : 1;
  guint is_char_stop : 1;
  guint is_word_stop : 1;
};

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


pango_shape ()

void        pango_shape                     (const gchar *text,
                                             gint length,
                                             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().

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


pango_justify ()

void        pango_justify                   (PangoGlyphString *glyphs,
                                             gint new_line_width,
                                             gint min_kashida_width);

glyphs : 
new_line_width : 
min_kashida_width :