Xft(3) X Version 11 Xft(3)

# [NAME](#NAME)

Xft - X FreeType interface library

# [SYNOPSIS](#SYNOPSIS)

**#include <X11/Xft/Xft.h>**

# [DESCRIPTION](#DESCRIPTION)

**Xft** is a simple library which draws text and graphics:

- using information provided by the Fontconfig library,
- **Xft** converts font glyphs using the FreeType rasterizer, and
- displays the converted font data using the X Rendering Extension.

This manual page barely scratches the surface of this library.

# [CONSTANTS](#CONSTANTS)

[**XFT\_MAJOR**](#XFT_MAJOR)

is the major version number of **Xft**.

[**XFT\_MINOR**](#XFT_MINOR)

is the minor version number of **Xft**.

[**XFT\_REVISION**](#XFT_REVISION)

is the revision number of **Xft**.

[**XFT\_VERSION**](#XFT_VERSION)

is **XFT\_MAJOR** times 10000 (ten thousand), plus **XFT\_MINOR** times 100, plus **XFT\_REVISION**.

[**XftVersion**](#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


```

# [DATA TYPES](#DATA_TYPES)

Xft datatypes follow a naming convention, prefixing all names with “Xft”

## [From Xlib...](#From_Xlib...)

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**:

[**Drawable**](#Drawable)

Declared in *<X11/X.h>*, this is an X resource ID, e.g., a window associated with a display. Both windows and pixmaps can be used as sources and destinations in graphics operations. These windows and pixmaps are collectively known as drawables. However, an **InputOnly** window cannot be used as a source or destination in a graphics operation.

[**Region**](#Region)

Declared in *<X11/Xutil.h>* and *<X11/Xregion.h>*, a **Region** is an arbitrary set of pixel locations which Xlib can manipulate. Internally, a **Region** is represented by the union of an arbitrary number of rectangles. Xlib maintains a rectangle which tells it the extent of this union.

[**Visual**](#Visual)

Declared in *<X11/Xutil.h>*, this structure contains information about the possible color mapping.

## [From XRender...](#From_XRender...)

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.

## [From Fontconfig...](#From_Fontconfig...)

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.

## [From FreeType 2...](#From_FreeType_2...)

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*.

## [XftFont](#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.

**XftFont**s are populated with any of **XftFontOpen**(), **XftFontOpenName**(), **XftFontOpenXlfd**(), **XftFontOpenInfo**(), or **XftFontOpenPattern**(). **XftFontCopy**() is used to duplicate **XftFont**s, and **XftFontClose**() is used to mark an **XftFont** as unused. **XftFont**s 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 **XftFont**s 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 **XftFont**s 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**](#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**](#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).

**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.

## [**XftDraw**](#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**(). **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.

## [**XftCharSpec**](#XftCharSpec)

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


```

**XftCharSpec** is used by **XftDrawCharSpec**(), and **XftCharSpecRender**().

## [**XftCharFontSpec**](#XftCharFontSpec)

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


```

**XftCharFontSpec** is used by **XftCharFontSpecRender**().

## [**XftGlyphSpec**](#XftGlyphSpec)

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


```

**XftGlyphSpec** is used by **XftDrawGlyphSpec**().

## [XftGlyphFontSpec](#XftGlyphFontSpec)

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


```

**XftGlyphFontSpec** is used by **XftDrawGlyphFontSpec**(), and **XftGlyphFontSpecRender**().

# [FUNCTIONS](#FUNCTIONS)

## [Initialization](#Initialization)

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.

**Bool** **XftDefaultHasRender** (

```
	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.

**Bool** **XftDefaultSet** (

```
	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.

**Xft** uses those properties initially to obtain these limits:

[XFT\_MAX\_GLYPH\_MEMORY](#XFT_MAX_GLYPH_MEMORY)

(maxglyphmemory). This is the maximum amount of glyph memory for all fonts used by **Xft** (default: 4\*1024\*1024).

[XFT\_MAX\_UNREF\_FONTS](#XFT_MAX_UNREF_FONTS)

(maxunreffonts). This is the maximum number of unreferenced fonts (default: 16).

[XFT\_TRACK\_MEM\_USAGE](#XFT_TRACK_MEM_USAGE)

(trackmemusage). When true, **Xft** tracks usage of glyph memory to improve performance when deciding which to unload when the maximum amount of glyph memory is reached (default: false).

**Xft** also uses these default properties in **XftDefaultSubstitute**().

**void** **XftDefaultSubstitute** (

```
	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**().

Typical **Xft** applications use this function to help Fontconfig choose a suitable font. These properties are substituted before calling **FcDefaultSubstitute**():

[FC\_ANTIALIAS](#FC_ANTIALIAS)

True if FreeType should use antialiasing (default: False). (default: True).

[FC\_AUTOHINT](#FC_AUTOHINT)

True if FreeType should use autohinting (default: False).

[FC\_DPI](#FC_DPI)

Dots/inch used for resolution (default: computed from the display height).

[FC\_EMBOLDEN](#FC_EMBOLDEN)

True if **FT\_GlyphSlot\_Embolden**() should be used to embolden a font (default: False).

[FC\_HINTING](#FC_HINTING)

True if hinting should be used when filling in properties to open a font (default: True).

[FC\_HINT\_STYLE](#FC_HINT_STYLE)

Hinting style used when filling in properties to open a font (default: FC\_HINT\_FULL).

[FC\_LCD\_FILTER](#FC_LCD_FILTER)

Parameter passed to **FT\_Library\_SetLcdFilter**() when loading glyphs (default: FC\_LCD\_DEFAULT).

[FC\_MINSPACE](#FC_MINSPACE)

Minimum space value used when filling in properties to open a font (default: False).

[FC\_RGBA](#FC_RGBA)

RGBA value used when filling in properties to open a font (default: computed by calling **XRenderQuerySubpixelOrder**()).

[FC\_SCALE](#FC_SCALE)

Scale used in Fontconfig (default: 1.0).

[XFT\_MAX\_GLYPH\_MEMORY](#XFT_MAX_GLYPH_MEMORY~2)

Maximum memory for one font (default: 1024\*1024).

[XFT\_RENDER](#XFT_RENDER)

True if the display supports X Render extension (default: result from **XftDefaultHasRender**()).

**FcBool** **XftInit** (

```
	_Xconst char	*config);


    
```

Initializes the Fontconfig library (calling **FcInit**()).

The *config* parameter is unused.

**Xft** does not deinitialize the Fontconfig library when it is done.

**FcBool** **XftInitFtLibrary** (**void**);

```


    
```

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.

**Xft** calls **XftInitFtLibrary**() internally via **XftFontInfoCreate**() and **XftFontOpenPattern**().

**Xft** does not discard the library object (e.g., using **FT\_Done\_FreeType**()) when it is done.

**int** **XftGetVersion** (**void**);

```


    
```

Return **XftVersion**, enabling an application to determine the actual version of **Xft** which is in use.

## [Opening and Matching Fonts](#Opening_and_Matching_Fonts)

**XftFont** \***XftFontOpen** (

```
	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);


```

This opens the “charter” font at 12 points. The point size is automatically converted to the correct pixel size based on the resolution of the monitor.

**XftFont** \***XftFontOpenName** (

```
	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).

**XftFont** \***XftFontOpenXlfd** (

```
	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.

**FcPattern** \***XftFontMatch** (

```
	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.

**FcPattern** \***XftXlfdParse** (

```
	_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*.

**XftXlfdParse** creates a Fontconfig pattern, setting the property **XFT\_XLFD** to the *xlfd\_orig* value, and maps the collected information to Fontconfig properties. Empty or “\*” fields are ignored:

[FC\_FOUNDRY](#FC_FOUNDRY)

from *foundry*.

[FC\_FAMILY](#FC_FAMILY)

from *family*.

[FC\_WEIGHT](#FC_WEIGHT)

*weight\_name*, defaulting to FC\_WEIGHT\_MEDIUM.

[FC\_SLANT](#FC_SLANT)

from *slant*, defaulting to FC\_SLANT\_ROMAN.

[FC\_SIZE](#FC_SIZE)

from *point\_size*.

[FC\_PIXEL\_SIZE](#FC_PIXEL_SIZE)

from *pixel\_size*. If *point\_size* was set, as well as *resolution\_x*and *resolution\_y*, then the value is scaled convert the font's height to points.

## [Families of Functions](#Families_of_Functions)

**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

## [Determining Text Extents](#Determining_Text_Extents)

**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*.

**void** **XftTextExtents8** (

```
	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*.

**void** **XftTextExtents16** (

```
	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*.

**void** **XftTextExtents32** (

```
	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*.

**void** **XftTextExtentsUtf8** (

```
	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*.

**void** **XftTextExtentsUtf16** (

```
	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*.

**void** **XftGlyphExtents** (

```
	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*.

If any of the *glyphs* are missing (determined by a check with **XftFontCheckGlyph**()), the corresponding entry in *extents* is filled with zeroes.

## [Managing XftColor](#Managing_XftColor)

**Bool** **XftColorAllocName** (

```
	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*.

- If **XAllocNamedColor**() returns nonzero, **XftColorAllocName**() fills in the resulting **XftColor** pixel field with the closest color supported by the screen, as well as the exact red, green and blue fields from the database, and returns True.
- If **XAllocNamedColor**() returns zero, **XftColorAllocName**() returns False, and does not update the **XftColor** referenced by *result*.

The *visual* parameter is unused.

**Bool** **XftColorAllocValue** (

```
	Display	*dpy,
	Visual	*visual,
	Colormap	 cmap,
	_Xconst XRenderColor	*color,
	XftColor	*result);


    
```

Allocate a color value:

- If the *visual* class is TrueColor, **XftColorAllocValue**() sets the *pixel* field in the **XftColor** referenced by *result* using the red, green and blue fields from the *color* parameter.
- If the *visual* class is not TrueColor, **XftColorAllocValue**() calls **XAllocColor**() to allocate an entry in the colormap *cmap*. which returns the pixel value of the color closest to the specified RGB elements supported by the hardware.

If **XAllocColor**() succeeds **XftColorAllocValue**() stores that pixel value in the **XRenderColor** referenced by *result* and returns True.

If **XAllocColor**() fails, **XftColorAllocValue**() returns False and does not modify the result.

**void** **XftColorFree** (

```
	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**().

## [Managing XftDraw](#Managing_XftDraw)

**XftDraw** \***XftDrawCreate** (

```
	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*.

**XftDraw** \***XftDrawCreateBitmap** (

```
	Display	*dpy,
	Pixmap	 bitmap);


    
```

**XftDrawCreateBitmap** behaves as **XftDrawCreate**(), except that it uses an X pixmap of color depth 1 instead of an X drawable.

**XftDraw \*** **XftDrawCreateAlpha** (

```
	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.

**void** **XftDrawChange** (

```
	XftDraw	*draw,
	Drawable	 drawable);


    
```

**XftDrawChange** changes the X drawable association of the existing **Xft** draw object *draw* from its current value to *drawable*.

**Display** \***XftDrawDisplay** (

```
	XftDraw	*draw);


    
```

**XftDrawDisplay** returns a pointer to the display associated with the **Xft** draw object *draw*.

**Drawable** **XftDrawDrawable** (

```
	XftDraw	*draw);


    
```

**XftDrawDrawable** returns the X drawable associated with the **Xft** draw object *draw*.

**Colormap** **XftDrawColormap** (

```
	XftDraw	*draw);


    
```

**XftDrawColormap**() returns the colormap associated with the **Xft** draw object *draw*.

**Visual** \***XftDrawVisual** (

```
	XftDraw	*draw);


    
```

**XftDrawVisual** returns a pointer to the visual associated with the **Xft** draw object *draw*.

**Picture** **XftDrawPicture** (

```
	XftDraw	*draw);


    
```

**XftDrawPicture** returns the picture associated with the **Xft** draw object *draw*.

If the X server does not support the X Rendering Extension, 0 is returned.

**Picture** **XftDrawSrcPicture** (

```
	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.

If the X server does not support the X Render extension, those functions use **XftGlyphCore**(), **XftGlyphSpecCore**(), or **XftGlyphFontSpecCore**().

**void** **XftDrawDestroy** (

```
	XftDraw	*draw);


    
```

**XftDrawDestroy** destroys *draw* (created by one of the **XftDrawCreate**\*() functions) and frees the memory that was allocated for it.

**Bool** **XftDrawSetClip** (

```
	XftDraw	*draw,
	Region	 r);


    
```

Set up clipping for the given **XftDraw** parameter *draw* starting with a **Region**:

- If the **Region** parameter *r* is not null, **Xft** creates a new **Region** (to copy the parameter),
- **Xft** destroys any existing clipping region.
- **Xft** sets the clip\_type for the *draw* parameter to **XftClipTypeRegion** if the *r* parameter was not null. Otherwise it sets the clip\_type to **XftClipTypeNone**.
- Finally, **Xft** updates clipping for existing objects, updates the clip\_mask for its X Render **Picture** object and sets the clipping-mask in the graphic context (GC) associated with the **XftDraw** parameter.

**XftDrawSetClip**() returns **True** if no change was necessary, or if the operation succeeded. It returns **False** if it was unable to create the new **Region**().

**Bool** **XftDrawSetClipRectangles** (

```
	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 .**

**Xft** sets the clip\_type for *draw* to XftClipTypeRectangles and uses **XSetClipRectangles**() for core (X11) clipping and **XRenderSetPictureClipRectangles**() for X Render clipping.

**void** **XftDrawSetSubwindowMode** (

```
	XftDraw	*draw,
	int	 mode);


    
```

Sets the subwindow-mode for the given **XftDraw** parameter *draw*. The mode can be either **ClipByChildren** (the default), or **IncludeInferiors**:

- For **ClipByChildren**, both source and destination windows are additionally clipped by all viewable **InputOutput** children.
- For **IncludeInferiors**, neither source nor destination window is clipped by inferiors. This will result in including subwindow contents in the source and drawing through subwindow boundaries of the destination.

In addition to the subwindow-mode maintained by **Xft**, it updates the subwindow mode for any associated graphics context **GC** using **XSetSubwindowMode**() as well as for an X Render **Picture** using **XRenderChangePicture**().

## [Drawing Strings](#Drawing_Strings)

**void** **XftDrawString8** (

```
	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*.

## [Drawing Other Things](#Drawing_Other_Things)

**void** **XftDrawRect** (

```
	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*.

**void** **XftCharFontSpecRender** (

```
	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.

**void** **XftDrawGlyphFontSpec** (

```
	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.

For each entry in the *glyphs* array:

- If the associated font uses the X Render extension, then **Xft** uses **XftGlyphFontSpecRender**() to draw the glyph, using a **Picture** obtained from calling **XftDrawSrcPicture ()** with the *draw* and *color* parameters.
- Otherwise, **Xft** provides an analogous feature using Xlib.

**void** **XftGlyphFontSpecRender** (

```
	Display	*dpy,
	int	 op,
	Picture	 src,
	Picture	 dst,
	int	 srcx,
	int	 srcy,
	_Xconst XftGlyphFontSpec	*glyphs,
	int	 nglyphs);


    
```

This involves several steps:

- First, **Xft** ensures that the *glyphs* array is complete using **XftFontCheckGlyph**() and loading any missing glyphs with **XftFontLoadGlyphs**().
- Then **Xft** examines the glyphs to find the maximum Unicode value. That determines the encoding size, i.e., the *width*.
- Then, for each glyph, **Xft** checks if its Unicode value is handled by the corresponding font. If not, the value is set to zero (0), to ignore it. While doing this, **Xft** also remembers which was the first font used, and computes the position at which each glyph will be drawn.
- **Xft** then constructs an equivalent array of glyphs in the format expected by the X Render library.
- Finally, **XftGlyphFontSpecRender**() uses the X Render extension to draw the glyphs, with the appropriate **XRenderCompositeText**\*() function according to the *width*, and discards temporary data.

The *op*, *dst*, *src*, *srcx*, and *srcy* parameters are used as described in the documentation for the X Render library.

## [Manipulating patterns](#Manipulating_patterns)

**FcFontSet** \***XftListFonts** (

```
	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**().

**FcPattern** \***XftNameParse** (

```
	_Xconst char	*name);


    
```

**Xft** uses Fontconfig to parse the name, passing the *name* to **FcNameParse**(), returning the result.

**FcBool** **XftNameUnparse** (

```
	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**.

## [Manipulating Font data](#Manipulating_Font_data)

**void** **XftFontLoadGlyphs** (

```
	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*.

Loading a glyph entails more than just reading data into memory. **Xft** uses the Fontconfig pattern associated with the display *dpy* (e.g., via **XftDefaultSet**()) to determine whether to use a bounding box, clip the glyphs into those bounds, scale the glyphs, compute font metrics, and add it to the X Render extension using **XRenderAddGlyphs**().

**void** **XftFontUnloadGlyphs** (

```
	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*.

**FT\_Face** **XftLockFace** (

```
	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.

Face-locking is used directly in **XftCharIndex**() and **XftFontLoadGlyphs**(), which in turn are used in many functions of **Xft**.

Face-locking was introduced in version 1 (October 2002). A few applications, such as Gdk/Gimp relied upon these functions. In version 2.1.9 (June 2006), face-locking was retained as part of the public API when improved shared-library configurations provided for hiding private symbols.

**void** **XftUnlockFace** (

```
	XftFont	*pub);


    
```

Decrements the reference count for the FreeType 2 “face” associated with the font.

**FT\_Face** objects are deallocated using **FT\_Done\_Face**(). **Xft** does this in **XftFontInfoDestroy**() and when cleaning up on failure in **XftFontInfoCreate**() and **XftFontOpenPattern**().

# [DEBUGGING](#DEBUGGING)

**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:

1

font-opening

2

additional font-matching and opening (verbose)

4

shows details about the **XRenderPictFormat** which will be used.

8

shows the string which **XftDrawString8**() will draw.

16

shows which font-ids are matched.

32

shows useful information about the glyphs which will be drawn

64

shows an ASCII-art representation of the glyphs.

128

shows details about the memory-cache management

256

shows details about managing glyph cached-memory

512

shows a report on memory-usage

1024

shows details on extended management of glyph cached-memory

# [COMPATIBILITY](#COMPATIBILITY)

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.

## [Xft 1.x Header File](#Xft_1.x_Header_File)

**#include <X11/Xft/XftCompat.h>**

## [Xft 1.x Data Types](#Xft_1.x_Data_Types)

[**XftPattern**](#XftPattern)

holds a set of names with associated value lists; each name refers to a property of a font. **XftPattern**s are used as inputs to the matching code as well as holding information about specific fonts.

[**XftFontSet**](#XftFontSet)

contains a list of **XftPattern**s. Internally, **Xft** uses this data structure to hold sets of fonts. Externally, **Xft** returns the results of listing fonts in this format.

[**XftObjectSet**](#XftObjectSet)

holds a set of names and is used to specify which fields from fonts are placed in the list of returned patterns when listing fonts.

# [AUTHORS](#AUTHORS)

Keith Packard  
Thomas E. Dickey (performance improvements)

# [SEE ALSO](#SEE_ALSO)

*Fontconfig Developers Reference*  
*FreeType API Reference*  
*Xlib - C Language Interface*  
*X Logical Font Description Conventions*

libXft 2.3.9 X Version 11

---

Document: XftTextExtents32(3) from libxft 2.3.9-r8 (Chainguard OS)
Source: https://gitlab.freedesktop.org/xorg/lib/libxft