Xft - X FreeType interface library

Xft is a simple library designed to interface the FreeType rasterizer with the X Rendering Extension. This manual page barely scratches the surface of this library.

#include <X11/Xft/Xft.h>

XFT_MAJOR

is the major version number of Xft.

XFT_MINOR

is the minor version number of Xft.

XFT_REVISION

is the revision number of Xft.

XFT_VERSION

is XFT_MAJOR times 10000 (ten thousand), plus XFT_MINOR times 100, plus XFT_REVISION.

XftVersion

is an alias for XFT_VERSION.

The following example illustrates how Xft's version constants might be used:

    #if (XFT_VERSION >= 20107)
    (void) puts("Version 2.1.7 or later of the Xft library is in"
                " use.");
    #else
    (void) printf("Insufficient version of Xft (%d.%d.%d) installed;
                  " need at least version 2.1.7.n", XFT_MAJOR,
                  XFT_MINOR,
                  XFT_REVISION);
    #endif

XftFont

typedef struct _XftFont {
    int         ascent;
    int         descent;
    int         height;
    int         max_advance_width;
    FcCharSet   *charset;
    FcPattern   *pattern;
} XftFont;

An XftFont is the primary data structure of interest to programmers using Xft; it contains general font metrics and pointers to the Fontconfig character set and pattern associated with the font. The FcCharSet and FcPattern data types are defined by the Fontconfig library.

XftFonts are populated with any of XftFontOpen(), XftFontOpenName(), XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPattern(). XftFontCopy() is used to duplicate XftFonts, and XftFontClose() is used to mark an XftFont as unused. XftFonts are internally allocated, reference-counted, and freed by Xft; the programmer does not ordinarily need to allocate or free storage for them.

XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), and XftDrawGlyphSpec() use XftFonts to render text to an XftDraw object, which may correspond to either a core X drawable or an X Rendering Extension drawable.

XftGlyphExtents() and the XftTextExtents*() family are used to determine the extents (maximum dimensions) of an XftFont.

An XftFont's glyph or character coverage can be determined with XftFontCheckGlyph() or XftCharExists(). XftCharIndex() returns the XftFont-specific character index corresponding to a given Unicode codepoint.

XftGlyphRender(), XftGlyphSpecRender(), XftCharSpecRender(), and the XftTextRender*() family use XftFonts to draw into X Rendering Extension Picture structures. Note: XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), and XftDrawGlyphSpec() provide a means of rendering fonts that is independent of the availability of the X Rendering Extension on the X server.

XftFontInfo

is an opaque object that stores information about a font. XftFontInfo structures are created with XftFontInfoCreate(), freed with XftFontInfoDestroy(), and compared with XftFontInfoEqual(). XftFontInfo objects are internally allocated and freed by Xft; the programmer does not ordinarily need to allocate or free storage for them.

Each XftFontInfo structure in use is associated with a unique identifier, which can be retrieved with XftFontInfoHash(). An XftFont can be opened based on XftFontInfo data with XftFontOpenInfo().

XftColor

typedef struct _XftColor {
    unsigned long   pixel;
    XRenderColor    color;
} XftColor;

An XftColor object permits text and other items to be rendered in a particular color (or the closest approximation offered by the X visual in use). The XRenderColor data type is defined by the X Render Extension library.

XftColorAllocName() and XftColorAllocValue() request a color allocation from the X server (if necessary) and initialize the members of XftColor. XftColorFree() instructs the X server to free the color currently allocated for an XftColor.

One an XftColor has been initialized, XftDrawSrcPicture(), XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), XftDrawCharFontSpec(), XftDrawGlyphSpec(), XftDrawGlyphFontSpec(), and XftDrawRect() may be used to draw various objects using it.

XftDraw

is an opaque object which holds information used to render to an X drawable using either the core protocol or the X Rendering extension.

XftDraw objects are created with any of XftDrawCreate() (which associates an XftDraw with an existing X drawable), XftDrawCreateBitmap(), or XftDrawCreateAlpha(), and destroyed with XftDrawDestroy(). The X drawable associated with an XftDraw can be changed with XftDrawChange(). XftDraws are internally allocated and freed by Xft; the programmer does not ordinarily need to allocate or free storage for them.

The X Display, Drawable, Colormap, and Visual of an XftDraw can be queried with XftDrawDisplay(), XftDrawDrawable(), XftDrawColormap(), and XftDrawVisual(), respectively. The X Rendering Extension Picture associated with an XftDraw is returned by XftDrawPicture().

XftCharSpec

typedef struct _XftCharSpec {
    FcChar32    ucs4;
    short       x;
    short       y;
} XftCharSpec;

The FcChar32 data type is defined by the Fontconfig library.

XftCharFontSpec

typedef struct _XftCharFontSpec {
    XftFont     *font;
    FcChar32    ucs4;
    short       x;
    short       y;
} XftCharFontSpec;

The FcChar32 data type is defined by the Fontconfig library.

XftGlyphSpec

typedef struct _XftGlyphSpec {
    FT_UInt     glyph;
    short       x;
    short       y;
} XftGlyphSpec;

The FT_UInt data type is defined by the FreeType library.

XftGlyphFontSpec

typedef struct _XftGlyphFontSpec {
    XftFont     *font;
    FT_UInt     glyph;
    short       x;
    short       y;
} XftGlyphFontSpec;

The FT_UInt data type is defined by the FreeType library.

Opening and Matching Fonts

XftFont *
XftFontOpen (Display *dpy,
             int     screen,
             ...);

    font = XftFontOpen (dpy, screen,
                        XFT_FAMILY, XftTypeString, "charter",
                        XFT_SIZE, XftTypeDouble, 12.0,
                        NULL);

XftFont *
XftFontOpenName (Display       *dpy,
                 int           screen,
                 unsigned char *name);

XftFont *
XftFontOpenXlfd (Display       *dpy,
                 int           screen,
                 unsigned char *xlfd)

FcPattern *
XftFontMatch (Display   *dpy,
              int       screen,
              FcPattern *pattern,
              FcResult  *result);

Determining the Pixel Extents of a Text String

void
XftTextExtents8 (Display    *dpy,
                 XftFont    *font,
                 FcChar8    *string,
                 int        len,
                 XGlyphInfo *extents);

void
XftTextExtents16 (Display    *dpy,
                  XftFont    *font,
                  FcChar16   *string,
                  int        len,
                  XGlyphInfo *extents);

void
XftTextExtents32 (Display    *dpy,
                  XftFont    *font,
                  FcChar32   *string,
                  int        len,
                  XGlyphInfo *extents);

void
XftTextExtentsUtf8 (Display    *dpy,
                    XftFont    *font,
                    FcChar8    *string,
                    int        len,
                    XGlyphInfo *extents);

void
XftTextExtentsUtf16 (Display    *dpy,
                     XftFont    *font,
                     FcChar8    *string,
                     FcEndian   endian,
                     int        len,
                     XGlyphInfo *extents);

void
XftGlyphExtents (Display    *dpy,
                 XftFont    *font,
                 FT_UInt    *glyphs,
                 int        nglyphs,
                 XGlyphInfo *extents);

Drawing Strings (and Other Things)

XftDraw *
XftDrawCreate (Display  *dpy,
               Drawable drawable,
               Visual   *visual,
               Colormap colormap);

XftDraw *
XftDrawCreateBitmap (Display *dpy,
                     Pixmap  bitmap);

XftDraw *
XftDrawCreateAlpha (Display *dpy,
                    Pixmap  pixmap,
                    int     depth);

void
XftDrawChange (XftDraw  *draw,
               Drawable drawable);

Display *
XftDrawDisplay (XftDraw *draw);

Drawable
XftDrawDrawable (XftDraw *draw);

Colormap
XftDrawColormap (XftDraw *draw);

Visual *
XftDrawVisual (XftDraw *draw);

Picture
XftDrawPicture (XftDraw *draw);

Picture
XftDrawSrcPicture (XftDraw *draw,
                   XftColor *color);

void
XftDrawDestroy (XftDraw *draw);

void
XftDrawString8 (XftDraw         *d,
                XRenderColor    *color,
                XftFont         *font,
                int             x,
                int             y,
                unsigned char   *string,
                int             len);

void
XftDrawRect (XftDraw        *d,
             XRenderColor   *color,
             int            x,
             int            y,
             unsigned int   width,
             unsigned int   height);

As of version 2, Xft has become relatively stable and is expected to retain source and binary compatibility in future releases.

Xft does provide a compatibility interface to its previous major version, Xft 1.x, described below.

Xft 1.x Compatibility Header File

Xft 1.x Compatibility Data Types

Keith Packard

Fontconfig Developers Reference

FreeType API Reference

Xlib - C Language Interface