How to Use SilGraphite with Xft Display Complex Text on Your Linux Application

Author: Frank Yung-Fong Tang <>
Version: Draft 0.1

This document discuss how should we make Linux application use SILGraphite to render Complex Text. It focus on how to patch the Xft String drawing functions and how to use Xft Glyph array drawing functions.

Xft provide three levels of text drawing function.
  1. Set 1: String drawing/measurement functions in Xft
  2. Set 2: Glyph drawing/measurement functions in Xft
  3. Set 3: Functions you should NOT use in Xft with complex text

The String drawing functions handle a string at a time. The character to glyph code conversion and the glyph placement is done inside the Xft. If you want to use these function to render complex text, you need to use a modify version of Xft which call the silgraphite.

The Glyph drawing functions handle the drawing of a string of Glyph. Some library or application currently ask Xft to convert character to glyph id first and then call these API to render the glyph. If you are using these API, you could modify your source to work with silgraphite without modify the Xft.

Some other function handle a string at a time, but the placement information is attach to the character level instead of glyph level. This mean there are no way we can reorder or adjust the glyph either inside Xft nor outside Xft. You should NOT use these functions if you want to work with complex text.

Using the following functions with the following Xft funtction with Complex Text mean  you need a modified version of Xft which intergrate with silgraphite. These function could be used to display simple static text, such as text in a bottm, menu, or list box. It is not good to use these functions to display editable text nor selectable text.
You don't need to use a modified version of Xft but you need to change your source code if you use the following Xft functions. You need to use these functions if the text you display is editable or selectable. You should also use these functions if your text may have multiple style (such as color) within a word in the complex text. For example, software like pango or Qt should use these functions.
Don't use the following Xft functions. They won't work with Complex Text:
It is not a good idea to use XftCharIndex because in the case of Complex Text, the relationship between character and glyph code is not necessary 1:1. Also, the mapping is contextual which mean the glyph code may change depend on the surrounding characters. Instead, the character to glyph conversion should be done by the GrEngine inside the silgraphite.

Base on these analysis, we decide to form the following projects:

Project GrXft:

Scope and Objective:

In this project, we modify the following Xft API to work with silgraphite to display/measure complex text if the font is a Graphite font:
This project won't help those application/library which call the Xft Glyph drawing routines (such as Pango). If the software is calling the Xft glyph drawing routines directly, we need to modify those software instead.



  1. Define a SilXftIsGraphiteFont( XftFont* pub) function
  2. For each target function, implement a SilXftXXX version
  3. For each target function XftXXX, add the coding pattern
    if ( SilXftIsGraphiteFont(pub)) {   
    in the beginning
  4. In the SilXftXXX function
    1. Implement a buch of conversion function which will convert 8, 16, and 32 bits string to UTF16 which accepted by SILGraphite
    2. Convert the string to UTF-16 and call SilXftTextExtentsCommon, SilXftDrawStringCommon,  SilXftTextRenderCommon
    3. In SilXftTextExtentsCommon, call SILGraphite
    4. In SilXftDrawStringCommon, call SILGraphite to convert the character string to an arry of GlyphSpec and call XftDrawGlyphSpec
    5. SilXftTextRenderCommon, call call SILGraphite to convert the character string to an arry of GlyphSpec and call XftGlyphSpecRender

Project GrPango: