1Xft(3) Library Functions Manual Xft(3)
2
6 Xft - X FreeType interface library
7
9 Xft is a simple library designed to interface the FreeType rasterizer
10 with the X Rendering Extension. This manual page barely scratches the
11 surface of this library.
12
14 #include <X11/Xft/Xft.h>
15
17 XFT_MAJOR
18 is the major version number of Xft.
19 XFT_MINOR
21 is the minor version number of Xft.
22 XFT_REVISION
24 is the revision number of Xft.
25 XFT_VERSION
27 is XFT_MAJOR times 10000 (ten thousand), plus XFT_MINOR times
28 100, plus XFT_REVISION.
29 XftVersion
31 is an alias for XFT_VERSION.
32 The following example illustrates how Xft's version constants might be
34 used:
35 #if (XFT_VERSION >= 20107)
36 (void) puts("Version 2.1.7 or later of the Xft library is in"
37 " use.");
38 #else
39 (void) printf("Insufficient version of Xft (%d.%d.%d) installed;
40 " need at least version 2.1.7.\n", XFT_MAJOR,
41 XFT_MINOR,
42 XFT_REVISION);
43 #endif
44
46 XftFont
47 typedef struct _XftFont {
48 int ascent;
49 int descent;
50 int height;
51 int max_advance_width;
52 FcCharSet *charset;
53 FcPattern *pattern;
54 } XftFont;
55 An XftFont is the primary data structure of interest to program‐
56 mers using Xft; it contains general font metrics and pointers to
57 the Fontconfig character set and pattern associated with the
58 font. The FcCharSet and FcPattern data types are defined by the
59 Fontconfig library.
60 XftFonts are populated with any of XftFontOpen(), XftFontOpen‐
62 Name(), XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPat‐
63 tern(). XftFontCopy() is used to duplicate XftFonts, and Xft‐
64 FontClose() is used to mark an XftFont as unused. XftFonts are
65 internally allocated, reference-counted, and freed by Xft; the
66 programmer does not ordinarily need to allocate or free storage
67 for them.
68 XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(),
70 and XftDrawGlyphSpec() use XftFonts to render text to an XftDraw
71 object, which may correspond to either a core X drawable or an X
72 Rendering Extension drawable.
73 XftGlyphExtents() and the XftTextExtents*() family are used to
75 determine the extents (maximum dimensions) of an XftFont.
76 An XftFont's glyph or character coverage can be determined with
78 XftFontCheckGlyph() or XftCharExists(). XftCharIndex() returns
79 the XftFont-specific character index corresponding to a given
80 Unicode codepoint.
81 XftGlyphRender(), XftGlyphSpecRender(), XftCharSpecRender(), and
83 the XftTextRender*() family use XftFonts to draw into X Render‐
84 ing Extension Picture structures. Note: XftDrawGlyphs(), the
85 XftDrawString*() family, XftDrawCharSpec(), and XftDrawGlyph‐
86 Spec() provide a means of rendering fonts that is independent of
87 the availability of the X Rendering Extension on the X server.
88 XftFontInfo
90 is an opaque object that stores information about a font. Xft‐
91 FontInfo structures are created with XftFontInfoCreate(), freed
92 with XftFontInfoDestroy(), and compared with XftFontInfoEqual().
93 XftFontInfo objects are internally allocated and freed by Xft;
94 the programmer does not ordinarily need to allocate or free
95 storage for them.
96 Each XftFontInfo structure in use is associated with a unique
98 identifier, which can be retrieved with XftFontInfoHash(). An
99 XftFont can be opened based on XftFontInfo data with Xft‐
100 FontOpenInfo().
101 XftColor
103 typedef struct _XftColor {
104 unsigned long pixel;
105 XRenderColor color;
106 } XftColor;
107 An XftColor object permits text and other items to be rendered
108 in a particular color (or the closest approximation offered by
109 the X visual in use). The XRenderColor data type is defined by
110 the X Render Extension library.
111 XftColorAllocName() and XftColorAllocValue() request a color al‐
113 location from the X server (if necessary) and initialize the
114 members of XftColor. XftColorFree() instructs the X server to
115 free the color currently allocated for an XftColor.
116 One an XftColor has been initialized, XftDrawSrcPicture(), Xft‐
118 DrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(),
119 XftDrawCharFontSpec(), XftDrawGlyphSpec(), XftDrawGlyph‐
120 FontSpec(), and XftDrawRect() may be used to draw various ob‐
121 jects using it.
122 XftDraw
124 is an opaque object which holds information used to render to an
125 X drawable using either the core protocol or the X Rendering ex‐
126 tension.
127 XftDraw objects are created with any of XftDrawCreate() (which
129 associates an XftDraw with an existing X drawable), XftDrawCre‐
130 ateBitmap(), or XftDrawCreateAlpha(), and destroyed with Xft‐
131 DrawDestroy(). The X drawable associated with an XftDraw can be
132 changed with XftDrawChange(). XftDraws are internally allocated
133 and freed by Xft; the programmer does not ordinarily need to al‐
134 locate or free storage for them.
135 The X Display, Drawable, Colormap, and Visual of an XftDraw can
137 be queried with XftDrawDisplay(), XftDrawDrawable(), XftDrawCol‐
138 ormap(), and XftDrawVisual(), respectively. The X Rendering Ex‐
139 tension Picture associated with an XftDraw is returned by Xft‐
140 DrawPicture().
141 XftCharSpec
143 typedef struct _XftCharSpec {
144 FcChar32 ucs4;
145 short x;
146 short y;
147 } XftCharSpec;
148 The FcChar32 data type is defined by the Fontconfig library.
150 XftCharFontSpec
152 typedef struct _XftCharFontSpec {
153 XftFont *font;
154 FcChar32 ucs4;
155 short x;
156 short y;
157 } XftCharFontSpec;
158 The FcChar32 data type is defined by the Fontconfig library.
160 XftGlyphSpec
162 typedef struct _XftGlyphSpec {
163 FT_UInt glyph;
164 short x;
165 short y;
166 } XftGlyphSpec;
167 The FT_UInt data type is defined by the FreeType library.
169 XftGlyphFontSpec
171 typedef struct _XftGlyphFontSpec {
172 XftFont *font;
173 FT_UInt glyph;
174 short x;
175 short y;
176 } XftGlyphFontSpec;
177 The FT_UInt data type is defined by the FreeType library.
179
181 Opening and Matching Fonts
182 XftFont *
183 XftFontOpen (Display *dpy,
184 int screen,
185 ...);
186 XftFontOpen takes a list of pattern element triples of the form field,
187 type, value (terminated with a NULL), matches that pattern against the
188 available fonts, and opens the matching font, sizing it correctly for
189 screen number screen on display dpy. The Display data type is defined
190 by the X11 library. Returns NULL if no match is found.
191 Example:
193 font = XftFontOpen (dpy, screen,
194 XFT_FAMILY, XftTypeString, "charter",
195 XFT_SIZE, XftTypeDouble, 12.0,
196 NULL);
197 This opens the “charter” font at 12 points. The point size is automat‐
198 ically converted to the correct pixel size based on the resolution of
199 the monitor.
200 XftFont *
202 XftFontOpenName (Display *dpy,
203 int screen,
204 unsigned char *name);
205 XftFontOpenName behaves as XftFontOpen does, except that it takes a
206 Fontconfig pattern string (which is passed to the Fontconfig library's
207 FcNameParse() function).
208 XftFont *
210 XftFontOpenXlfd (Display *dpy,
211 int screen,
212 unsigned char *xlfd)
213 XftFontOpenXlfd behaves as XftFontOpen does, except that it takes a
214 string containing an X Logical Font Description (XLFD).
215 FcPattern *
217 XftFontMatch (Display *dpy,
218 int screen,
219 FcPattern *pattern,
220 FcResult *result);
221 Also used internally by the XftFontOpen* functions, XftFontMatch can
222 also be used directly to determine the Fontconfig font pattern result‐
223 ing from an Xft font open request. The FcPattern and FcResult data
224 types are defined by the Fontconfig library.
225 Determining the Pixel Extents of a Text String
227 void
228 XftTextExtents8 (Display *dpy,
229 XftFont *font,
230 FcChar8 *string,
231 int len,
232 XGlyphInfo *extents);
233 XftTextExtents8 computes the pixel extents on display dpy of no more
234 than len glyphs of a string consisting of eight-bit characters when
235 drawn with font, storing them in extents. The FcChar8 data type is de‐
236 fined by the Fontconfig library, and the XGlyphInfo data type is de‐
237 fined by the X Rendering Extension library.
238 void
240 XftTextExtents16 (Display *dpy,
241 XftFont *font,
242 FcChar16 *string,
243 int len,
244 XGlyphInfo *extents);
245 XftTextExtents16 computes the pixel extents on display dpy of no more
246 than len glyphs of a string consisting of sixteen-bit characters when
247 drawn with font, storing them in extents. The FcChar16 data type is
248 defined by the Fontconfig library, and the XGlyphInfo data type is de‐
249 fined by the X Rendering Extension library.
250 void
252 XftTextExtents32 (Display *dpy,
253 XftFont *font,
254 FcChar32 *string,
255 int len,
256 XGlyphInfo *extents);
257 XftTextExtents32 computes the pixel extents on display dpy of no more
258 than len glyphs of a string consisting of thirty-two-bit characters
259 when drawn with font, storing them in extents. The FcChar32 data type
260 is defined by the Fontconfig library, and the XGlyphInfo data type is
261 defined by the X Rendering Extension library.
262 void
264 XftTextExtentsUtf8 (Display *dpy,
265 XftFont *font,
266 FcChar8 *string,
267 int len,
268 XGlyphInfo *extents);
269 XftTextExtentsUtf8 computes the pixel extents on display dpy of no more
270 than len bytes of a UTF-8 encoded string when drawn with font, storing
271 them in extents. The XGlyphInfo data type is defined by the X Render‐
272 ing Extension library.
273 void
275 XftTextExtentsUtf16 (Display *dpy,
276 XftFont *font,
277 FcChar8 *string,
278 FcEndian endian,
279 int len,
280 XGlyphInfo *extents);
281 XftTextExtentsUtf16 computes the pixel extents on display dpy of no
282 more than len bytes of a UTF-16LE- or UTF-16BE-encoded string when
283 drawn with font, storing them in extents. The endianness of string
284 must be specified in endian. The FcEndian data type is defined by the
285 Fontconfig library, and the XGlyphInfo data type is defined by the X
286 Rendering Extension library.
287 void
289 XftGlyphExtents (Display *dpy,
290 XftFont *font,
291 FT_UInt *glyphs,
292 int nglyphs,
293 XGlyphInfo *extents);
294 Also used internally by the XftTextExtents* functions, XftGlyphExtents
295 computes the pixel extents on display dpy of no more than nglyphs in
296 the array glyphs drawn with font, storing them in extents. The FT_UInt
297 data type is defined by the FreeType library, and the XGlyphInfo data
298 type is defined by the X Rendering Extension library.
299 Drawing Strings (and Other Things)
301 XftDraw *
302 XftDrawCreate (Display *dpy,
303 Drawable drawable,
304 Visual *visual,
305 Colormap colormap);
306 XftDrawCreate creates a structure that can be used to render text and
307 rectangles using the specified drawable, visual, and colormap on dis‐
308 play. The Drawable, Visual, and Colormap data types are defined by the
309 X11 library.
310 XftDraw *
312 XftDrawCreateBitmap (Display *dpy,
313 Pixmap bitmap);
314 XftDrawCreateBitmap behaves as XftDrawCreate, except it uses an X
315 pixmap of color depth 1 instead of an X drawable. The Pixmap data type
316 is defined by the X11 library.
317 XftDraw *
319 XftDrawCreateAlpha (Display *dpy,
320 Pixmap pixmap,
321 int depth);
322 XftDrawCreateAlpha behaves as XftDrawCreate, except it uses an X pixmap
323 of color depth depth instead of an X drawable. The Pixmap data type is
324 defined by the X11 library.
325 void
327 XftDrawChange (XftDraw *draw,
328 Drawable drawable);
329 XftDrawChange changes the X drawable association of the existing Xft
330 draw object draw from its current value to drawable.
331 Display *
333 XftDrawDisplay (XftDraw *draw);
334 XftDrawDisplay returns a pointer to the display associated with the Xft
335 draw object draw.
336 Drawable
338 XftDrawDrawable (XftDraw *draw);
339 XftDrawDrawable returns the X drawable associated with the Xft draw ob‐
340 ject draw.
341 Colormap
343 XftDrawColormap (XftDraw *draw);
344 XftDrawColormap returns the colormap associated with the Xft draw ob‐
345 ject draw.
346 Visual *
348 XftDrawVisual (XftDraw *draw);
349 XftDrawVisual returns a pointer to the visual associated with the Xft
350 draw object draw.
351 Picture
353 XftDrawPicture (XftDraw *draw);
354 XftDrawPicture returns the picture associated with the Xft draw object
355 draw. If the the X server does not support the X Rendering Extension,
356 0 is returned.
357 Picture
359 XftDrawSrcPicture (XftDraw *draw,
360 XftColor *color);
361 This function is never called if the X server doesn't support the X
362 Rendering Extension; instead, XftGlyphCore is used.
363 void
365 XftDrawDestroy (XftDraw *draw);
366 XftDrawDestroy destroys draw (created by one of the XftCreate func‐
367 tions) and frees the memory that was allocated for it.
368 void
370 XftDrawString8 (XftDraw *d,
371 XftColor *color,
372 XftFont *font,
373 int x,
374 int y,
375 unsigned char *string,
376 int len);
377 XftDrawString8 draws no more than len glyphs of string to Xft drawable
378 d using font in color at position x, y.
379 void
381 XftDrawRect (XftDraw *d,
382 XftColor *color,
383 int x,
384 int y,
385 unsigned int width,
386 unsigned int height);
387 XftDrawRect draws a solid rectangle of the specified color, width, and
388 height at position x, y to Xft drawable d.
389
391 As of version 2, Xft has become relatively stable and is expected to
392 retain source and binary compatibility in future releases.
393 Xft does provide a compatibility interface to its previous major ver‐
395 sion, Xft 1.x, described below.
396 Xft 1.x Compatibility Header File
398 #include <X11/Xft/XftCompat.h>
399 Xft 1.x Compatibility Data Types
401 XftPattern
402 holds a set of names with associated value lists; each name
403 refers to a property of a font. XftPatterns are used as inputs
404 to the matching code as well as holding information about spe‐
405 cific fonts.
406 XftFontSet
408 contains a list of XftPatterns. Internally, Xft uses this data
409 structure to hold sets of fonts. Externally, Xft returns the
410 results of listing fonts in this format.
411 XftObjectSet
413 holds a set of names and is used to specify which fields from
414 fonts are placed in the the list of returned patterns when list‐
415 ing fonts.
416
418 Keith Packard
419
421 Fontconfig Developers Reference
422 FreeType API Reference
423 Xlib - C Language Interface
424X Version 11 libXft 2.3.4 Xft(3)