| Xft(3) | X Version 11 | Xft(3) |
Xft - X FreeType interface library
Xft is a simple library which draws text and graphics:
This manual page barely scratches the surface of this library.
#include <X11/Xft/Xft.h>
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
Xft datatypes follow a naming convention, prefixing all names with “Xft”
Xlib datatypes do not follow a naming convention. They are documented in Xlib - C Language Interface.
Xft uses these names: Bool, Colormap, Display, Drawable, Pixmap, Region, Visual, and XRectangle.
Some datatypes are especially relevant to Xft:
The X Render Extension library datatypes are inspired by Xlib, but lack the corresponding documentation. Refer to the header file for details:
<X11/extensions/Xrender.h>
or read the source code (which provides an outline of libXrender).
Xft uses these names: Picture, XGlyphInfo, XRenderColor.
Fontconfig datatypes follow a naming convention, prefixing all names with “Fc” which are documented in Fontconfig Developers Reference.
Xft uses these Fontconfig names: FcBool, FcChar8, FcChar16, FcChar32, FcCharSet, FcEndian, FcFontSet, FcPattern, and FcResult.
FreeType 2 datatypes follow a naming convention, prefixing all names with “FT_” which are documented in FreeType API Reference.
Xft uses these names: FT_Face, FT_Library, and FT_UInt.
FreeType 2 uses FT_UInt (an unsigned integer) to represent glyphs.
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.
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.
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().
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).
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.
Once 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.
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(). XftDraw objects 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 properties of an XftDraw can be queried with XftDrawDisplay(), XftDrawDrawable(), XftDrawColormap(), and XftDrawVisual(), respectively.
Several functions use XftDraw objects: XftDrawCharFontSpec(), XftDrawCharSpec(), XftDrawGlyphFontSpec(), XftDrawGlyphSpec(), XftDrawGlyphs(), XftDrawRect(), XftDrawSetClip(), XftDrawSetClipRectangles(), XftDrawSetSubwindowMode(), and the XftDrawString*() family.
The X Rendering Extension Picture associated with an XftDraw is returned by XftDrawPicture(), and XftDrawSrcPicture(). It is used by XftCharFontSpecRender(), XftCharSpecRender(), XftGlyphFontSpecRender(), XftGlyphRender(), XftGlyphSpecRender(), and the XftTextRender*() family.
typedef struct _XftCharSpec {
FcChar32 ucs4;
short x;
short y;
} XftCharSpec;
XftCharSpec is used by XftDrawCharSpec(), and XftCharSpecRender().
typedef struct _XftCharFontSpec {
XftFont *font;
FcChar32 ucs4;
short x;
short y;
} XftCharFontSpec;
XftCharFontSpec is used by XftCharFontSpecRender().
typedef struct _XftGlyphSpec {
FT_UInt glyph;
short x;
short y;
} XftGlyphSpec;
XftGlyphSpec is used by XftDrawGlyphSpec().
typedef struct _XftGlyphFontSpec {
XftFont *font;
FT_UInt glyph;
short x;
short y;
} XftGlyphFontSpec;
XftGlyphFontSpec is used by XftDrawGlyphFontSpec(), and XftGlyphFontSpecRender().
A typical application using Xft does not explicitly initialize the library. That is usually done as a side-effect of opening a font.
When Xft initializes, it collects information about the display, and stores some of that information in a Fontconfig pattern (essentially a collection of properties with typed values). The calling application can modify that pattern to change the library's behavior.
Not all of the collected information is stored in a pattern. The remainder is stored in internal data structures. Xft makes some of that available to the application via functions.
Display *dpy);
Obtain information about the display dpy if not done already, and return true if Xft found that the display supports the X Render extension, and if it is able to find a suitable XRenderPictFormat (X Render's datatype which is analogous to Xlib's Visual) on the display.
Display *dpy, FcPattern *defaults);
Obtain information about the display dpy if not done already, and set the Fontconfig pattern holding default properties which Xft will use for this display.
Display *dpy, int screen, FcPattern *pattern);
Xft fills in missing properties in the given pattern using default properties for the specified display dpy, e.g., as set in XftDefaultSet().
_Xconst char *config);
Initializes the Fontconfig library (calling FcInit()).
Initializes the FreeType library (calling FT_Init_FreeType() to create a library object) if it has not already been initialized. This is needed before using the FreeType library to read font data from a file.
Return XftVersion, enabling an application to determine the actual version of Xft which is in use.
Display *dpy, int screen, ...);
XftFontOpen takes a list of pattern element triples of the form field, type, value (terminated with a NULL), matches that pattern against the available fonts, and opens the matching font, sizing it correctly for screen number screen on display dpy. Return the matched font, or NULL if no match is found.
Example:
font = XftFontOpen (dpy, screen,
XFT_FAMILY, XftTypeString, "charter",
XFT_SIZE, XftTypeDouble, 12.0,
NULL);
Display *dpy, int screen, _Xconst char *name);
XftFontOpenName behaves as XftFontOpen does, except that it takes a Fontconfig pattern string (which is passed to the Fontconfig library's FcNameParse() function).
Display *dpy, int screen, _Xconst char *xlfd)
XftFontOpenXlfd behaves as XftFontOpen does, except that it takes a string containing an X Logical Font Description (XLFD), and uses the XftXlfdParse() function.
Display *dpy, int screen, _Xconst FcPattern *pattern, FcResult *result);
Also used internally by the XftFontOpen* functions, XftFontMatch can also be used directly to determine the Fontconfig font pattern resulting from an Xft font open request.
_Xconst char *xlfd_orig, Bool ignore_scalable, Bool complete);
XftXlfdParse parses the xlfd_orig parameter according to the X Logical Font Description Conventions document, but ignores some of the fields: setwidth_name, add_style_name, spacing, and average_width.
Xft provides groups of drawing functions which differ according to the way the data is encoded, e.g., 8-bit (ISO-8859-1) versus UTF-8. Here is a summary of these related functions:
| Encoding | XftDrawString* | XftTextExtents* | XftTextRender* |
| 8 | XftDrawString8 | XftTextExtents8 | XftTextRender8 |
| 16 | XftDrawString16 | XftTextExtents16 | XftTextRender16 |
| 16BE | XftDrawString16 | XftTextExtents16 | XftTextRender16BE |
| 16LE | XftDrawString16 | XftTextExtents16 | XftTextRender16LE |
| 32 | XftDrawString32 | XftTextExtents32 | XftTextRender32 |
| 32BE | XftDrawString32 | XftTextExtents32 | XftTextRender32BE |
| 32LE | XftDrawString32 | XftTextExtents32 | XftTextRender32LE |
| UTF-8 | XftDrawStringUtf8 | XftTextExtentsUtf8 | XftTextRenderUtf8 |
| UTF-16 | XftDrawStringUtf16 | XftTextExtentsUtf16 | XftTextRenderUtf16 |
Xft provides several functions for determining the required height and width for displaying a text-string. After accounting for the offset, in cases where the string will be shifted up, down, left or right, these numbers are referred to as text extents.
Display *dpy, XftFont *font, _Xconst FcChar8 *string, int len, XGlyphInfo *extents);
XftTextExtents8 computes the pixel extents on display dpy of no more than len glyphs of a string consisting of eight-bit characters when drawn with font, storing them in extents.
Display *dpy, XftFont *font, _Xconst FcChar16 *string, int len, XGlyphInfo *extents);
XftTextExtents16 computes the pixel extents on display dpy of no more than len glyphs of a string consisting of sixteen-bit characters when drawn with font, storing them in extents.
Display *dpy, XftFont *font, _Xconst FcChar32 *string, int len, XGlyphInfo *extents);
XftTextExtents32 computes the pixel extents on display dpy of no more than len glyphs of a string consisting of thirty-two-bit characters when drawn with font, storing them in extents.
Display *dpy, XftFont *font, _Xconst FcChar8 *string, int len, XGlyphInfo *extents);
XftTextExtentsUtf8 computes the pixel extents on display dpy of no more than len bytes of a UTF-8 encoded string when drawn with font, storing them in extents.
Display *dpy, XftFont *font, _Xconst FcChar8 *string, FcEndian endian, int len, XGlyphInfo *extents);
XftTextExtentsUtf16 computes the pixel extents on display dpy of no more than len bytes of a UTF-16LE- or UTF-16BE-encoded string when drawn with font, storing them in extents. The endianness of string must be specified in endian.
Display *dpy, XftFont *font, _Xconst FT_UInt *glyphs, int nglyphs, XGlyphInfo *extents);
Also used internally by the XftTextExtents*() functions, XftGlyphExtents computes the pixel extents on display dpy of no more than nglyphs in the array glyphs drawn with font, storing them in extents.
Display *dpy, _Xconst Visual *visual, Colormap cmap, _Xconst char *name, XftColor *result);
Use XAllocNamedColor() to look up the named color name for the screen associated with the colormap cmap.
Display *dpy, Visual *visual, Colormap cmap, _Xconst XRenderColor *color, XftColor *result);
Allocate a color value:
Display *dpy, Visual *visual, Colormap cmap, XftColor *color);
If the visual class is not TrueColor, Xft calls XFreeColors() to free the entry from the colormap cmap whose pixel value in the color parameter was allocated by XftColorAllocName().
Display *dpy, Drawable drawable, Visual *visual, Colormap colormap);
XftDrawCreate creates a structure that can be used to render text and rectangles using the specified drawable, visual, and colormap on display.
Display *dpy, Pixmap bitmap);
XftDrawCreateBitmap behaves as XftDrawCreate(), except that it uses an X pixmap of color depth 1 instead of an X drawable.
Display *dpy, Pixmap pixmap, int depth);
XftDrawCreateAlpha behaves as XftDrawCreate(), except that it uses an X pixmap of color depth depth instead of an X drawable.
XftDraw *draw, Drawable drawable);
XftDrawChange changes the X drawable association of the existing Xft draw object draw from its current value to drawable.
XftDraw *draw);
XftDrawDisplay returns a pointer to the display associated with the Xft draw object draw.
XftDraw *draw);
XftDrawDrawable returns the X drawable associated with the Xft draw object draw.
XftDraw *draw);
XftDrawColormap() returns the colormap associated with the Xft draw object draw.
XftDraw *draw);
XftDrawVisual returns a pointer to the visual associated with the Xft draw object draw.
XftDraw *draw);
XftDrawPicture returns the picture associated with the Xft draw object draw.
XftDraw *draw, _Xconst XftColor *color);
Return an X Render Picture object, which is used for rendering glyphs, e.g., with XftGlyphRender(), XftGlyphSpecRender(), or XftGlyphFontSpecRender(), by XftDrawGlyphs(), XftDrawGlyphSpec(), XftDrawGlyphFontSpec(), respectively.
XftDraw *draw);
XftDrawDestroy destroys draw (created by one of the XftDrawCreate*() functions) and frees the memory that was allocated for it.
XftDraw *draw, Region r);
Set up clipping for the given XftDraw parameter draw starting with a Region:
XftDraw *draw, int xOrigin, int yOrigin, _Xconst XRectangle *rects, int n);
Like XftDrawSetClip(), XftDrawSetClipRectangles() sets up clipping for the given XftDraw parameter draw but uses a set of n rectangles (the rects parameter) which could be used to construct a Region .
XftDraw *draw, int mode);
Sets the subwindow-mode for the given XftDraw parameter draw. The mode can be either ClipByChildren (the default), or IncludeInferiors:
XftDraw *d, _Xconst XftColor *color, XftFont *font, int x, int y, _Xconst FcChar8 *string, int len);
XftDrawString8 draws no more than len glyphs of string to Xft drawable d using font in color at position x, y.
XftDraw *d, _Xconst XftColor *color, int x, int y, unsigned int width, unsigned int height);
XftDrawRect draws a solid rectangle of the specified color, width, and height at position x, y to Xft drawable d.
Display *dpy, int op, Picture src, Picture dst, int srcx, int srcy, _Xconst XftCharFontSpec *chars, int len);
XftCharFontSpecRender() converts the chars parameter from XftCharFontSpec to XftGlyphFontSpec, passing the converted array along with the other parameters unchanged to XftGlyphFontSpecRender() to render the data.
XftDraw *draw, _Xconst XftColor *color, _Xconst XftGlyphFontSpec *glyphs, int len);
Draw a list of glyphs associated with fonts at specified coordinates, passed as an array of len XftGlyphFontSpec structures via the parameter glyphs. All of the glyphs are drawn using the color specified in the color parameter.
Display *dpy, int op, Picture src, Picture dst, int srcx, int srcy, _Xconst XftGlyphFontSpec *glyphs, int nglyphs);
This involves several steps:
Display *dpy, int screen, ...);
Xft uses FcPatternVapBuild() and FcObjectSetVapBuild() to process the variable-length parameter list, and FcFontList() to obtain a list of matching Fontconfig patterns, which it returns to the caller. The caller can dispose of the return value using FcPatternDestroy().
_Xconst char *name);
Xft uses Fontconfig to parse the name, passing the name to FcNameParse(), returning the result.
FcPattern *pat, char *dest, int len);
Like XfgNameParse(), Xft uses Fontconfig. In this case, it uses FcNameUnparse(), which converts the pattern pat back into a string that can be parsed. XftNameUnparse() stores the result via the caller's pointer dest, but checks first if it will fit, using the len parameter. If it fits, Xft copies the string and returns FcTrue, otherwise it returns FcFalse.
Display *dpy, XftFont *pub, FcBool need_bitmaps, _Xconst FT_UInt *glyphs, int nglyph);
Using FT_Load_Glyph(), load nglyphs for the glyph indices (Unicode values) listed in the array glyphs from the given font pub.
Display *dpy, XftFont *pub, _Xconst FT_UInt *glyphs, int nglyph);
Discards data for up to nglyph glyphs whose glyph indices (Unicode values) are listed in the array glyphs for the given font pub. If the glyphs were added to the X Render extension, Xft removes those using XRenderFreeGlyphs(). Xft keeps track of the amount of memory used for glyphs, and updates the usage associated with the display dpy.
XftFont *pub);
If no FreeType 2 “face” (in-memory representation of a given typeface in a given style) has been created for the pub font, create one using FT_New_Face(). Face-locks are a reference count used by Xft to ensure that only one face is created, and that it is retained until the font is no longer used.
XftFont *pub);
Decrements the reference count for the FreeType 2 “face” associated with the font.
Xft reads the environment variable XFT_DEBUG and converts that to an integer. Each bit in the resulting value tells Xft to print debugging information to the standard output:
As of version 2 (May 2002), Xft became relatively stable. It is expected to retain source and binary compatibility in future releases.
Xft provides a compatibility interface to its previous major version, Xft 1.x, described below.
#include <X11/Xft/XftCompat.h>
Keith Packard
Thomas E. Dickey (performance improvements)
Fontconfig Developers Reference
FreeType API Reference
Xlib - C Language Interface
X Logical Font Description Conventions
| libXft 2.3.6 | X Version 11 |