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

Author: Frank Yung-Fong Tang <ytang0648@aol.com>
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.

Set 1: String drawing/measurement functions in Xft
Set 2: Glyph drawing/measurement functions in Xft
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.

XftDrawString8, XftDrawString16, XftDrawString32, XftDrawStringUtf8, XftDrawStringUtf16
XftTextExtents8, XftTextExtents16, XftTextExtents32, XftTextExtentsUtf8, XftTextExtentsUtf16
XftTextRender8, XftTextRender16, XftTextRender16BE, XftTextRender16LE, XftTextRender32, XftTextRender32BE, XftTextRender32LE, XftTextRenderUtf8, XftTextRenderUtf16

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.

XftDrawGlyphs, XftDrawGlyphSpec, XftDrawGlyphFontSpec, XftGlyphExtents, XftGlyphRender, XftGlyphSpecRender, XftGlyphFontSpecRender

Don't use the following Xft functions. They won't work with Complex Text:

XftDrawCharSpec, XftDrawCharFontSpec, XftCharSpecRender, XftCharFontSpecRender, XftCharIndex

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: To produce a patch to modify the Set 1 functions above in Xft to use silgraphite to display Complex Text.
Project GrPango: To produce a patch to modify the Pango to use silgraphite and Set 2 functions above in Xft to work with Complex Text

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:

XftDrawString8, XftDrawString16, XftDrawString32, XftDrawStringUtf8, XftDrawStringUtf16
XftTextExtents8, XftTextExtents16, XftTextExtents32, XftTextExtentsUtf8, XftTextExtentsUtf16
XftTextRender8, XftTextRender16, XftTextRender16BE, XftTextRender16LE, XftTextRender32, XftTextRender32BE, XftTextRender32LE, XftTextRenderUtf8, XftTextRenderUtf16

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.

Issues:

Use C++ in Xft: Xft is written in C but not C++. However, SILGraphite currently provide C++ interface. The C interface is not ready yet. Two possible approaches:

First make the SILGraphite C interface ready, then work on this project. Use pure C in the patch
Use C++ to produce the patch. Ignore the fact that currently Xft only use C. This could be a fast way to produce prototype. And the majority of the framework could be convert to the C implementation when the SILGraphite C interface is ready.

How to test Graphite font.

Design:

Define a SilXftIsGraphiteFont( XftFont* pub) function
For each target function, implement a SilXftXXX version

For each target function XftXXX, add the coding pattern

if ( SilXftIsGraphiteFont(pub)) {   
    SilXftXXX();
    return;
}

in the beginning

In the SilXftXXX function

Implement a buch of conversion function which will convert 8, 16, and 32 bits string to UTF16 which accepted by SILGraphite
Convert the string to UTF-16 and call SilXftTextExtentsCommon, SilXftDrawStringCommon, SilXftTextRenderCommon
In SilXftTextExtentsCommon, call SILGraphite
In SilXftDrawStringCommon, call SILGraphite to convert the character string to an arry of GlyphSpec and call XftDrawGlyphSpec
SilXftTextRenderCommon, call call SILGraphite to convert the character string to an arry of GlyphSpec and call XftGlyphSpecRender

Project GrPango:

Scope:

Issues:

C vs C++ interface issue: Same as in GrXft
Coverage model

Design:

Modify from the basic-xft and basic-ft2, produce two shape engine, graphite-xft and graphite-ft2.
Take a look at the module/basic directory about how to make a basic-xft and basic-ft2 shaper
For each engine, we need to implement 3 major functions

a shape function
a get_coverage function
a script_break function