1Xft(3) X Version 11 Xft(3)
2
6 Xft - X FreeType interface library
7
9 Xft is a simple library which draws text and graphics:
10 • using information provided by the Fontconfig library,
12 • Xft converts font glyphs using the FreeType rasterizer, and
14 • displays the converted font data using the X Rendering Extension.
16 This manual page barely scratches the surface of this library.
18
20 #include <X11/Xft/Xft.h>
21
23 XFT_MAJOR
24 is the major version number of Xft.
25 XFT_MINOR
27 is the minor version number of Xft.
28 XFT_REVISION
30 is the revision number of Xft.
31 XFT_VERSION
33 is XFT_MAJOR times 10000 (ten thousand), plus XFT_MINOR times
34 100, plus XFT_REVISION.
35 XftVersion
37 is an alias for XFT_VERSION.
38 The following example illustrates how Xft's version constants might be
40 used:
41 #if (XFT_VERSION >= 20107)
42 (void) puts("Version 2.1.7 or later of the Xft library is in"
43 " use.");
44 #else
45 (void) printf("Insufficient version of Xft (%d.%d.%d) installed;
46 " need at least version 2.1.7.\n", XFT_MAJOR,
47 XFT_MINOR,
48 XFT_REVISION);
49 #endif
50
52 Xft datatypes follow a naming convention, prefixing all names with
53 “Xft”
54 From Xlib...
56 Xlib datatypes do not follow a naming convention. They are documented
57 in Xlib - C Language Interface.
58 Xft uses these names: Bool, Colormap, Display, Drawable, Pixmap, Re‐
60 gion, Visual, and XRectangle.
61 Some datatypes are especially relevant to Xft:
63 Drawable
65 Declared in <X11/X.h>, this is an X resource ID, e.g., a window
66 associated with a display. Both windows and pixmaps can be used
67 as sources and destinations in graphics operations. These windows
68 and pixmaps are collectively known as drawables. However, an In‐
69 putOnly window cannot be used as a source or destination in a
70 graphics operation.
71 Region
73 Declared in <X11/Xutil.h> and <X11/Xregion.h>, a Region is an ar‐
74 bitrary set of pixel locations which Xlib can manipulate. Inter‐
75 nally, a Region is represented by the union of an arbitrary number
76 of rectangles. Xlib maintains a rectangle which tells it the ex‐
77 tent of this union.
78 Visual
80 Declared in <X11/Xutil.h>, this structure contains information
81 about the possible color mapping.
82 From XRender...
84 The X Render Extension library datatypes are inspired by Xlib, but lack
85 the corresponding documentation. Refer to the header file for details:
86 <X11/extensions/Xrender.h>
88 or read the source code (which provides an outline of libXrender).
90 Xft uses these names: Picture, XGlyphInfo, XRenderColor.
92 From Fontconfig...
94 Fontconfig datatypes follow a naming convention, prefixing all names
95 with “Fc” which are documented in Fontconfig Developers Reference.
96 Xft uses these Fontconfig names: FcBool, FcChar8, FcChar16, FcChar32,
98 FcCharSet, FcEndian, FcFontSet, FcPattern, and FcResult.
99 From FreeType 2...
101 FreeType 2 datatypes follow a naming convention, prefixing all names
102 with “FT_” which are documented in FreeType API Reference.
103 Xft uses these names: FT_Face, FT_Library, and FT_UInt.
105 FreeType 2 uses FT_UInt (an unsigned integer) to represent glyphs.
107 XftFont
109 typedef struct _XftFont {
110 int ascent;
111 int descent;
112 int height;
113 int max_advance_width;
114 FcCharSet *charset;
115 FcPattern *pattern;
116 } XftFont;
117 An XftFont is the primary data structure of interest to programmers us‐
119 ing Xft; it contains general font metrics and pointers to the Fontcon‐
120 fig character set and pattern associated with the font.
121 XftFonts are populated with any of XftFontOpen(), XftFontOpenName(),
123 XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPattern(). Xft‐
124 FontCopy() is used to duplicate XftFonts, and XftFontClose() is used to
125 mark an XftFont as unused. XftFonts are internally allocated, refer‐
126 ence-counted, and freed by Xft; the programmer does not ordinarily need
127 to allocate or free storage for them.
128 XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(), and
130 XftDrawGlyphSpec() use XftFonts to render text to an XftDraw object,
131 which may correspond to either a core X drawable or an X Rendering Ex‐
132 tension drawable.
133 XftGlyphExtents() and the XftTextExtents*() family are used to deter‐
135 mine the extents (maximum dimensions) of an XftFont.
136 An XftFont's glyph or character coverage can be determined with Xft‐
138 FontCheckGlyph() or XftCharExists(). XftCharIndex() returns the Xft‐
139 Font-specific character index corresponding to a given Unicode code‐
140 point.
141 XftGlyphRender(), XftGlyphSpecRender(), XftCharSpecRender(), and the
143 XftTextRender*() family use XftFonts to draw into X Rendering Extension
144 Picture structures.
145 Note: XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(),
147 and XftDrawGlyphSpec() provide a means of rendering fonts that is inde‐
148 pendent of the availability of the X Rendering Extension on the X
149 server.
150 XftFontInfo
152 is an opaque object that stores information about a font. XftFontInfo
153 structures are created with XftFontInfoCreate(), freed with XftFontIn‐
154 foDestroy(), and compared with XftFontInfoEqual(). XftFontInfo objects
155 are internally allocated and freed by Xft; the programmer does not or‐
156 dinarily need to allocate or free storage for them.
157 Each XftFontInfo structure in use is associated with a unique identi‐
159 fier, which can be retrieved with XftFontInfoHash(). An XftFont can be
160 opened based on XftFontInfo data with XftFontOpenInfo().
161 XftColor
163 typedef struct _XftColor {
164 unsigned long pixel;
165 XRenderColor color;
166 } XftColor;
167 An XftColor object permits text and other items to be rendered in a
169 particular color (or the closest approximation offered by the X visual
170 in use).
171 XftColorAllocName() and XftColorAllocValue() request a color allocation
173 from the X server (if necessary) and initialize the members of Xft‐
174 Color. XftColorFree() instructs the X server to free the color cur‐
175 rently allocated for an XftColor.
176 Once an XftColor has been initialized, XftDrawSrcPicture(), XftDrawG‐
178 lyphs(), the XftDrawString*() family, XftDrawCharSpec(), XftDrawChar‐
179 FontSpec(), XftDrawGlyphSpec(), XftDrawGlyphFontSpec(), and Xft‐
180 DrawRect() may be used to draw various objects using it.
181 XftDraw
183 is an opaque object which holds information used to render to an X
184 drawable using either the core protocol or the X Rendering extension.
185 XftDraw objects are created with any of XftDrawCreate() (which asso‐
187 ciates an XftDraw with an existing X drawable), XftDrawCreateBitmap(),
188 or XftDrawCreateAlpha(), and destroyed with XftDrawDestroy(). The X
189 drawable associated with an XftDraw can be changed with Xft‐
190 DrawChange(). XftDraw objects are internally allocated and freed by
191 Xft; the programmer does not ordinarily need to allocate or free stor‐
192 age for them.
193 The X Display, Drawable, Colormap, and Visual properties of an XftDraw
195 can be queried with XftDrawDisplay(), XftDrawDrawable(), XftDrawCol‐
196 ormap(), and XftDrawVisual(), respectively.
197 Several functions use XftDraw objects: XftDrawCharFontSpec(), Xft‐
199 DrawCharSpec(), XftDrawGlyphFontSpec(), XftDrawGlyphSpec(), XftDrawG‐
200 lyphs(), XftDrawRect(), XftDrawSetClip(), XftDrawSetClipRectangles(),
201 XftDrawSetSubwindowMode(), and the XftDrawString*() family.
202 The X Rendering Extension Picture associated with an XftDraw is re‐
204 turned by XftDrawPicture(), and XftDrawSrcPicture(). It is used by
205 XftCharFontSpecRender(), XftCharSpecRender(), XftGlyphFontSpecRender(),
206 XftGlyphRender(), XftGlyphSpecRender(), and the XftTextRender*() fam‐
207 ily.
208 XftCharSpec
210 typedef struct _XftCharSpec {
211 FcChar32 ucs4;
212 short x;
213 short y;
214 } XftCharSpec;
215 XftCharSpec is used by XftDrawCharSpec(), and XftCharSpecRender().
217 XftCharFontSpec
219 typedef struct _XftCharFontSpec {
220 XftFont *font;
221 FcChar32 ucs4;
222 short x;
223 short y;
224 } XftCharFontSpec;
225 XftCharFontSpec is used by XftCharFontSpecRender().
227 XftGlyphSpec
229 typedef struct _XftGlyphSpec {
230 FT_UInt glyph;
231 short x;
232 short y;
233 } XftGlyphSpec;
234 XftGlyphSpec is used by XftDrawGlyphSpec().
236 XftGlyphFontSpec
238 typedef struct _XftGlyphFontSpec {
239 XftFont *font;
240 FT_UInt glyph;
241 short x;
242 short y;
243 } XftGlyphFontSpec;
244 XftGlyphFontSpec is used by XftDrawGlyphFontSpec(), and XftGlyph‐
246 FontSpecRender().
247
249 Initialization
250 A typical application using Xft does not explicitly initialize the li‐
251 brary. That is usually done as a side-effect of opening a font.
252 When Xft initializes, it collects information about the display, and
254 stores some of that information in a Fontconfig pattern (essentially a
255 collection of properties with typed values). The calling application
256 can modify that pattern to change the library's behavior.
257 Not all of the collected information is stored in a pattern. The re‐
259 mainder is stored in internal data structures. Xft makes some of that
260 available to the application via functions.
261 Bool XftDefaultHasRender (
263 Display *dpy);
264 Obtain information about the display dpy if not done already,
266 and return true if Xft found that the display supports the X
267 Render extension, and if it is able to find a suitable XRender‐
268 PictFormat (X Render's datatype which is analogous to Xlib's
269 Visual) on the display.
270 Bool XftDefaultSet (
272 Display *dpy,
273 FcPattern *defaults);
274 Obtain information about the display dpy if not done already,
276 and set the Fontconfig pattern holding default properties which
277 Xft will use for this display.
278 Xft uses those properties initially to obtain these limits:
280 XFT_MAX_GLYPH_MEMORY
282 (maxglyphmemory). This is the maximum amount of glyph
283 memory for all fonts used by Xft (default: 4*1024*1024).
284 XFT_MAX_UNREF_FONTS
286 (maxunreffonts). This is the maximum number of unrefer‐
287 enced fonts (default: 16).
288 XFT_TRACK_MEM_USAGE
290 (trackmemusage). When true, Xft tracks usage of glyph
291 memory to improve performance when deciding which to un‐
292 load when the maximum amount of glyph memory is reached
293 (default: false).
294 Xft also uses these default properties in XftDefaultSubsti‐
296 tute().
297 void XftDefaultSubstitute (
299 Display *dpy,
300 int screen,
301 FcPattern *pattern);
302 Xft fills in missing properties in the given pattern using de‐
304 fault properties for the specified display dpy, e.g., as set in
305 XftDefaultSet().
306 Typical Xft applications use this function to help Fontconfig
308 choose a suitable font. These properties are substituted before
309 calling FcDefaultSubstitute():
310 FC_ANTIALIAS
312 True if FreeType should use antialiasing (default:
313 False). (default: True).
314 FC_AUTOHINT
316 True if FreeType should use autohinting (default:
317 False).
318 FC_DPI
320 Dots/inch used for resolution (default: computed from
321 the display height).
322 FC_EMBOLDEN
324 True if FT_GlyphSlot_Embolden() should be used to em‐
325 bolden a font (default: False).
326 FC_HINTING
328 True if hinting should be used when filling in proper‐
329 ties to open a font (default: True).
330 FC_HINT_STYLE
332 Hinting style used when filling in properties to open a
333 font (default: FC_HINT_FULL).
334 FC_LCD_FILTER
336 Parameter passed to FT_Library_SetLcdFilter() when load‐
337 ing glyphs (default: FC_LCD_DEFAULT).
338 FC_MINSPACE
340 Minimum space value used when filling in properties to
341 open a font (default: False).
342 FC_RGBA
344 RGBA value used when filling in properties to open a
345 font (default: computed by calling XRenderQuerySubpix‐
346 elOrder()).
347 FC_SCALE
349 Scale used in Fontconfig (default: 1.0).
350 XFT_MAX_GLYPH_MEMORY
352 Maximum memory for one font (default: 1024*1024).
353 XFT_RENDER
355 True if the display supports X Render extension (de‐
356 fault: result from XftDefaultHasRender()).
357 FcBool XftInit (
359 _Xconst char *config);
360 Initializes the Fontconfig library (calling FcInit()).
362 The config parameter is unused.
364 Xft does not deinitialize the Fontconfig library when it is
366 done.
367 FcBool XftInitFtLibrary (void);
369 Initializes the FreeType library (calling FT_Init_FreeType() to
371 create a library object) if it has not already been initialized.
372 This is needed before using the FreeType library to read font
373 data from a file.
374 Xft calls XftInitFtLibrary() internally via XftFontInfoCreate()
376 and XftFontOpenPattern().
377 Xft does not discard the library object (e.g., using
379 FT_Done_FreeType()) when it is done.
380 int XftGetVersion (void);
382 Return XftVersion, enabling an application to determine the ac‐
384 tual version of Xft which is in use.
385 Opening and Matching Fonts
387 XftFont *XftFontOpen (
388 Display *dpy,
389 int screen,
390 ...);
391 XftFontOpen takes a list of pattern element triples of the form
393 field, type, value (terminated with a NULL), matches that pat‐
394 tern against the available fonts, and opens the matching font,
395 sizing it correctly for screen number screen on display dpy.
396 Return the matched font, or NULL if no match is found.
397 Example:
399 font = XftFontOpen (dpy, screen,
400 XFT_FAMILY, XftTypeString, "charter",
401 XFT_SIZE, XftTypeDouble, 12.0,
402 NULL);
403 This opens the “charter” font at 12 points. The point size is
405 automatically converted to the correct pixel size based on the
406 resolution of the monitor.
407 XftFont *XftFontOpenName (
409 Display *dpy,
410 int screen,
411 _Xconst char *name);
412 XftFontOpenName behaves as XftFontOpen does, except that it
414 takes a Fontconfig pattern string (which is passed to the Font‐
415 config library's FcNameParse() function).
416 XftFont *XftFontOpenXlfd (
418 Display *dpy,
419 int screen,
420 _Xconst char *xlfd)
421 XftFontOpenXlfd behaves as XftFontOpen does, except that it
423 takes a string containing an X Logical Font Description (XLFD),
424 and uses the XftXlfdParse() function.
425 FcPattern *XftFontMatch (
427 Display *dpy,
428 int screen,
429 _Xconst FcPattern *pattern,
430 FcResult *result);
431 Also used internally by the XftFontOpen* functions, XftFontMatch
433 can also be used directly to determine the Fontconfig font pat‐
434 tern resulting from an Xft font open request.
435 FcPattern *XftXlfdParse (
437 _Xconst char *xlfd_orig,
438 Bool ignore_scalable,
439 Bool complete);
440 XftXlfdParse parses the xlfd_orig parameter according to the X
442 Logical Font Description Conventions document, but ignores some
443 of the fields: setwidth_name, add_style_name, spacing, and aver‐
444 age_width.
445 XftXlfdParse creates a Fontconfig pattern, setting the property
447 XFT_XLFD to the xlfd_orig value, and maps the collected informa‐
448 tion to Fontconfig properties. Empty or “*” fields are ignored:
449 FC_FOUNDRY
451 from foundry.
452 FC_FAMILY
454 from family.
455 FC_WEIGHT
457 weight_name, defaulting to FC_WEIGHT_MEDIUM.
458 FC_SLANT
460 from slant, defaulting to FC_SLANT_ROMAN.
461 FC_SIZE
463 from point_size.
464 FC_PIXEL_SIZE
466 from pixel_size. If point_size was set, as well as res‐
467 olution_xand resolution_y, then the value is scaled con‐
468 vert the font's height to points.
469 Families of Functions
471 Xft provides groups of drawing functions which differ according to the
472 way the data is encoded, e.g., 8-bit (ISO-8859-1) versus UTF-8. Here
473 is a summary of these related functions:
474 Encoding XftDrawString* XftTextExtents* XftTextRender*
476 ─────────────────────────────────────────────────────────────────────────
477 8 XftDrawString8 XftTextExtents8 XftTextRender8
478 16 XftDrawString16 XftTextExtents16 XftTextRender16
479 16BE XftDrawString16 XftTextExtents16 XftTextRender16BE
480 16LE XftDrawString16 XftTextExtents16 XftTextRender16LE
481 32 XftDrawString32 XftTextExtents32 XftTextRender32
482 32BE XftDrawString32 XftTextExtents32 XftTextRender32BE
483 32LE XftDrawString32 XftTextExtents32 XftTextRender32LE
484 UTF-8 XftDrawStringUtf8 XftTextExtentsUtf8 XftTextRenderUtf8
485 UTF-16 XftDrawStringUtf16 XftTextExtentsUtf16 XftTextRenderUtf16
486 Determining Text Extents
488 Xft provides several functions for determining the required height and
489 width for displaying a text-string. After accounting for the offset,
490 in cases where the string will be shifted up, down, left or right,
491 these numbers are referred to as text extents.
492 void XftTextExtents8 (
494 Display *dpy,
495 XftFont *font,
496 _Xconst FcChar8 *string,
497 int len,
498 XGlyphInfo *extents);
499 XftTextExtents8 computes the pixel extents on display dpy of no
501 more than len glyphs of a string consisting of eight-bit charac‐
502 ters when drawn with font, storing them in extents.
503 void XftTextExtents16 (
505 Display *dpy,
506 XftFont *font,
507 _Xconst FcChar16 *string,
508 int len,
509 XGlyphInfo *extents);
510 XftTextExtents16 computes the pixel extents on display dpy of no
512 more than len glyphs of a string consisting of sixteen-bit char‐
513 acters when drawn with font, storing them in extents.
514 void XftTextExtents32 (
516 Display *dpy,
517 XftFont *font,
518 _Xconst FcChar32 *string,
519 int len,
520 XGlyphInfo *extents);
521 XftTextExtents32 computes the pixel extents on display dpy of no
523 more than len glyphs of a string consisting of thirty-two-bit
524 characters when drawn with font, storing them in extents.
525 void XftTextExtentsUtf8 (
527 Display *dpy,
528 XftFont *font,
529 _Xconst FcChar8 *string,
530 int len,
531 XGlyphInfo *extents);
532 XftTextExtentsUtf8 computes the pixel extents on display dpy of
534 no more than len bytes of a UTF-8 encoded string when drawn with
535 font, storing them in extents.
536 void XftTextExtentsUtf16 (
538 Display *dpy,
539 XftFont *font,
540 _Xconst FcChar8 *string,
541 FcEndian endian,
542 int len,
543 XGlyphInfo *extents);
544 XftTextExtentsUtf16 computes the pixel extents on display dpy of
546 no more than len bytes of a UTF-16LE- or UTF-16BE-encoded string
547 when drawn with font, storing them in extents. The endianness
548 of string must be specified in endian.
549 void XftGlyphExtents (
551 Display *dpy,
552 XftFont *font,
553 _Xconst FT_UInt *glyphs,
554 int nglyphs,
555 XGlyphInfo *extents);
556 Also used internally by the XftTextExtents*() functions, XftG‐
558 lyphExtents computes the pixel extents on display dpy of no more
559 than nglyphs in the array glyphs drawn with font, storing them
560 in extents.
561 If any of the glyphs are missing (determined by a check with
563 XftFontCheckGlyph()), the corresponding entry in extents is
564 filled with zeroes.
565 Managing XftColor
567 Bool XftColorAllocName (
568 Display *dpy,
569 _Xconst Visual *visual,
570 Colormap cmap,
571 _Xconst char *name,
572 XftColor *result);
573 Use XAllocNamedColor() to look up the named color name for the
575 screen associated with the colormap cmap.
576 • If XAllocNamedColor() returns nonzero, XftColorAllocName()
578 fills in the resulting XftColor pixel field with the closest
579 color supported by the screen, as well as the exact red,
580 green and blue fields from the database, and returns True.
581 • If XAllocNamedColor() returns zero, XftColorAllocName() re‐
583 turns False, and does not update the XftColor referenced by
584 result.
585 The visual parameter is unused.
587 Bool XftColorAllocValue (
589 Display *dpy,
590 Visual *visual,
591 Colormap cmap,
592 _Xconst XRenderColor *color,
593 XftColor *result);
594 Allocate a color value:
596 • If the visual class is TrueColor, XftColorAllocValue() sets
598 the pixel field in the XftColor referenced by result using
599 the red, green and blue fields from the color parameter.
600 • If the visual class is not TrueColor, XftColorAllocValue()
602 calls XAllocColor() to allocate an entry in the colormap
603 cmap. which returns the pixel value of the color closest to
604 the specified RGB elements supported by the hardware.
605 If XAllocColor() succeeds XftColorAllocValue() stores that
607 pixel value in the XRenderColor referenced by result and re‐
608 turns True.
609 If XAllocColor() fails, XftColorAllocValue() returns False
611 and does not modify the result.
612 void XftColorFree (
614 Display *dpy,
615 Visual *visual,
616 Colormap cmap,
617 XftColor *color);
618 If the visual class is not TrueColor, Xft calls XFreeColors() to
620 free the entry from the colormap cmap whose pixel value in the
621 color parameter was allocated by XftColorAllocName().
622 Managing XftDraw
624 XftDraw *XftDrawCreate (
625 Display *dpy,
626 Drawable drawable,
627 Visual *visual,
628 Colormap colormap);
629 XftDrawCreate creates a structure that can be used to render
631 text and rectangles using the specified drawable, visual, and
632 colormap on display.
633 XftDraw *XftDrawCreateBitmap (
635 Display *dpy,
636 Pixmap bitmap);
637 XftDrawCreateBitmap behaves as XftDrawCreate(), except that it
639 uses an X pixmap of color depth 1 instead of an X drawable.
640 XftDraw * XftDrawCreateAlpha (
642 Display *dpy,
643 Pixmap pixmap,
644 int depth);
645 XftDrawCreateAlpha behaves as XftDrawCreate(), except that it
647 uses an X pixmap of color depth depth instead of an X drawable.
648 void XftDrawChange (
650 XftDraw *draw,
651 Drawable drawable);
652 XftDrawChange changes the X drawable association of the existing
654 Xft draw object draw from its current value to drawable.
655 Display *XftDrawDisplay (
657 XftDraw *draw);
658 XftDrawDisplay returns a pointer to the display associated with
660 the Xft draw object draw.
661 Drawable XftDrawDrawable (
663 XftDraw *draw);
664 XftDrawDrawable returns the X drawable associated with the Xft
666 draw object draw.
667 Colormap XftDrawColormap (
669 XftDraw *draw);
670 XftDrawColormap() returns the colormap associated with the Xft
672 draw object draw.
673 Visual *XftDrawVisual (
675 XftDraw *draw);
676 XftDrawVisual returns a pointer to the visual associated with
678 the Xft draw object draw.
679 Picture XftDrawPicture (
681 XftDraw *draw);
682 XftDrawPicture returns the picture associated with the Xft draw
684 object draw.
685 If the the X server does not support the X Rendering Extension,
687 0 is returned.
688 Picture XftDrawSrcPicture (
690 XftDraw *draw,
691 _Xconst XftColor *color);
692 Return an X Render Picture object, which is used for rendering
694 glyphs, e.g., with XftGlyphRender(), XftGlyphSpecRender(), or
695 XftGlyphFontSpecRender(), by XftDrawGlyphs(), XftDrawGlyph‐
696 Spec(), XftDrawGlyphFontSpec(), respectively.
697 If the X server does not support the X Render extension, those
699 functions use XftGlyphCore(), XftGlyphSpecCore(), or XftGlyph‐
700 FontSpecCore().
701 void XftDrawDestroy (
703 XftDraw *draw);
704 XftDrawDestroy destroys draw (created by one of the XftDrawCre‐
706 ate*() functions) and frees the memory that was allocated for
707 it.
708 Bool XftDrawSetClip (
710 XftDraw *draw,
711 Region r);
712 Set up clipping for the given XftDraw parameter draw starting
714 with a Region:
715 • If the Region parameter r is not null, Xft creates a new Re‐
717 gion (to copy the parameter),
718 • Xft destroys any existing clipping region.
720 • Xft sets the clip_type for the draw parameter to XftClip‐
722 TypeRegion if the r parameter was not null. Otherwise it
723 sets the clip_type to XftClipTypeNone.
724 • Finally, Xft updates clipping for existing objects, updates
726 the clip_mask for its X Render Picture object and sets the
727 clipping-mask in the graphic context (GC) associated with
728 the XftDraw parameter.
729 XftDrawSetClip() returns True if no change was necessary, or if
731 the operation succeeded. It returns False if it was unable to
732 create the new Region().
733 Bool XftDrawSetClipRectangles (
735 XftDraw *draw,
736 int xOrigin,
737 int yOrigin,
738 _Xconst XRectangle *rects,
739 int n);
740 Like XftDrawSetClip(), XftDrawSetClipRectangles() sets up clip‐
742 ping for the given XftDraw parameter draw but uses a set of n
743 rectangles (the rects parameter) which could be used to con‐
744 struct a Region .
745 Xft sets the clip_type for draw to XftClipTypeRectangles and
747 uses XSetClipRectangles() for core (X11) clipping and XRender‐
748 SetPictureClipRectangles() for X Render clipping.
749 void XftDrawSetSubwindowMode (
751 XftDraw *draw,
752 int mode);
753 Sets the subwindow-mode for the given XftDraw parameter draw.
755 The mode can be either ClipByChildren (the default), or Include‐
756 Inferiors:
757 • For ClipByChildren, both source and destination windows are
759 additionally clipped by all viewable InputOutput children.
760 • For IncludeInferiors, neither source nor destination window
762 is clipped by inferiors. This will result in including sub‐
763 window contents in the source and drawing through subwindow
764 boundaries of the destination.
765 In addition to the subwindow-mode maintained by Xft, it updates
767 the subwindow mode for any associated graphics context GC using
768 XSetSubwindowMode() as well as for an X Render Picture using
769 XRenderChangePicture().
770 Drawing Strings
772 void XftDrawString8 (
773 XftDraw *d,
774 _Xconst XftColor *color,
775 XftFont *font,
776 int x,
777 int y,
778 _Xconst FcChar8 *string,
779 int len);
780 XftDrawString8 draws no more than len glyphs of string to Xft
782 drawable d using font in color at position x, y.
783 Drawing Other Things
785 void XftDrawRect (
786 XftDraw *d,
787 _Xconst XftColor *color,
788 int x,
789 int y,
790 unsigned int width,
791 unsigned int height);
792 XftDrawRect draws a solid rectangle of the specified color,
794 width, and height at position x, y to Xft drawable d.
795 void XftCharFontSpecRender (
797 Display *dpy,
798 int op,
799 Picture src,
800 Picture dst,
801 int srcx,
802 int srcy,
803 _Xconst XftCharFontSpec*chars,
804 int len);
805 XftCharFontSpecRender() converts the chars parameter from
807 XftCharFontSpec to XftGlyphFontSpec, passing the converted array
808 along with the other parameters unchanged to XftGlyph‐
809 FontSpecRender() to render the data.
810 void XftDrawGlyphFontSpec (
812 XftDraw *draw,
813 _Xconst XftColor *color,
814 _Xconst XftGlyphFontSpec*glyphs,
815 int len);
816 Draw a list of glyphs associated with fonts at specified coordi‐
818 nates, passed as an array of len XftGlyphFontSpec structures via
819 the parameter glyphs. All of the glyphs are drawn using the
820 color specified in the color parameter.
821 For each entry in the glyphs array:
823 • If the associated font uses the X Render extension, then Xft
825 uses XftGlyphFontSpecRender() to draw the glyph, using a
826 Picture obtained from calling XftDrawSrcPicture () with the
827 draw and color parameters.
828 • Otherwise, Xft provides an analogous feature using Xlib.
830 void XftGlyphFontSpecRender (
832 Display *dpy,
833 int op,
834 Picture src,
835 Picture dst,
836 int srcx,
837 int srcy,
838 _Xconst XftGlyphFontSpec*glyphs,
839 int nglyphs);
840 This involves several steps:
842 • First, Xft ensures that the glyphs array is complete using
844 XftFontCheckGlyph() and loading any missing glyphs with Xft‐
845 FontLoadGlyphs().
846 • Then Xft examines the glyphs to find the maximum Unicode
848 value. That determines the encoding size, i.e., the width.
849 • Then, for each glyph, Xft checks if its Unicode value is
851 handled by the corresponding font. If not, the value is set
852 to zero (0), to ignore it. While doing this, Xft also re‐
853 members which was the first font used, and computes the po‐
854 sition at which each glyph will be drawn.
855 • Xft then constructs an equivalent array of glyphs in the
857 format expected by the X Render library.
858 • Finally, XftGlyphFontSpecRender() uses the X Render exten‐
860 sion to draw the glyphs, with the appropriate XRenderCompos‐
861 iteText*() function according to the width, and discards
862 temporary data.
863 The op, dst, src, srcx, and srcy parameters are used as de‐
865 scribed in the documentation for the X Render library.
866 Manipulating patterns
868 FcFontSet *XftListFonts (
869 Display *dpy,
870 int screen,
871 ...);
872 Xft uses FcPatternVapBuild() and FcObjectSetVapBuild() to
874 process the variable-length parameter list, and FcFontList() to
875 obtain a list of matching Fontconfig patterns, which it returns
876 to the caller. The caller can dispose of the return value using
877 FcPatternDestroy().
878 FcPattern *XftNameParse (
880 _Xconst char *name);
881 Xft uses Fontconfig to parse the name, passing the name to Fc‐
883 NameParse(), returning the result.
884 FcBool XftNameUnparse (
886 FcPattern *pat,
887 char *dest,
888 int len);
889 Like XfgNameParse(), Xft uses Fontconfig. In this case, it uses
891 FcNameUnparse(), which converts the pattern pat back into a
892 string that can be parsed. XftNameUnparse() stores the result
893 via the caller's pointer dest, but checks first if it will fit,
894 using the len parameter. If it fits, Xft copies the string and
895 returns FcTrue, otherwise it returns FcFalse.
896 Manipulating Font data
898 void XftFontLoadGlyphs (
899 Display *dpy,
900 XftFont *pub,
901 FcBool need_bitmaps,
902 _Xconst FT_UInt *glyphs,
903 int nglyph);
904 Using FT_Load_Glyph(), load nglyphs for the glyph indices (Uni‐
906 code values) listed in the array glyphs from the given font pub.
907 Loading a glyph entails more than just reading data into memory.
909 Xft uses the Fontconfig pattern associated with the display dpy
910 (e.g., via XftDefaultSet()) to determine whether to use a bound‐
911 ing box, clip the glyphs into those bounds, scale the glyphs,
912 compute font metrics, and add it to the X Render extension using
913 XRenderAddGlyphs().
914 void XftFontUnloadGlyphs (
916 Display *dpy,
917 XftFont *pub,
918 _Xconst FT_UInt *glyphs,
919 int nglyph);
920 Discards data for up to nglyph glyphs whose glyph indices (Uni‐
922 code values) are listed in the array glyphs for the given font
923 pub. If the glyphs were added to the X Render extension, Xft
924 removes those using XRenderFreeGlyphs(). Xft keeps track of the
925 amount of memory used for glyphs, and updates the usage associ‐
926 ated with the display dpy.
927 FT_Face XftLockFace (
929 XftFont *pub);
930 If no FreeType 2 “face” (in-memory representation of a given
932 typeface in a given style) has been created for the pub font,
933 create one using FT_New_Face(). Face-locks are a reference
934 count used by Xft to ensure that only one face is created, and
935 that it is retained until the font is no longer used.
936 Face-locking is used directly in XftCharIndex() and XftFontLoad‐
938 Glyphs(), which in turn are used in many functions of Xft.
939 Face-locking was introduced in version 1 (October 2002). A few
941 applications, such as Gdk/Gimp relied upon these functions. In
942 version 2.1.9 (June 2006), face-locking was retained as part of
943 the public API when improved shared-library configurations pro‐
944 vided for hiding private symbols.
945 void XftUnlockFace (
947 XftFont *pub);
948 Decrements the reference count for the FreeType 2 “face” associ‐
950 ated with the font.
951 FT_Face objects are deallocated using FT_Done_Face(). Xft does
953 this in XftFontInfoDestroy() and when cleaning up on failure in
954 XftFontInfoCreate() and XftFontOpenPattern().
955
957 Xft reads the environment variable XFT_DEBUG and converts that to an
958 integer. Each bit in the resulting value tells Xft to print debugging
959 information to the standard output:
960 1 font-opening
962 2 additional font-matching and opening (verbose)
964 4 shows details about the XRenderPictFormat which will be used.
966 8 shows the string which XftDrawString8() will draw.
968 16 shows which font-ids are matched.
970 32 shows useful information about the glyphs which will be drawn
972 64 shows an ASCII-art representation of the glyphs.
974 128 shows details about the memory-cache management
976 256 shows details about managing glyph cached-memory
978 512 shows a report on memory-usage
980 1024 shows details on extended management of glyph cached-memory
982
984 As of version 2 (May 2002), Xft became relatively stable. It is ex‐
985 pected to retain source and binary compatibility in future releases.
986 Xft provides a compatibility interface to its previous major version,
988 Xft 1.x, described below.
989 Xft 1.x Header File
991 #include <X11/Xft/XftCompat.h>
992 Xft 1.x Data Types
994 XftPattern
995 holds a set of names with associated value lists; each name
996 refers to a property of a font. XftPatterns are used as inputs
997 to the matching code as well as holding information about spe‐
998 cific fonts.
999 XftFontSet
1001 contains a list of XftPatterns. Internally, Xft uses this data
1002 structure to hold sets of fonts. Externally, Xft returns the
1003 results of listing fonts in this format.
1004 XftObjectSet
1006 holds a set of names and is used to specify which fields from
1007 fonts are placed in the the list of returned patterns when list‐
1008 ing fonts.
1009
1011 Keith Packard
1012 Thomas E. Dickey (performance improvements)
1013
1015 Fontconfig Developers Reference
1016 FreeType API Reference
1017 Xlib - C Language Interface
1018 X Logical Font Description Conventions
1019X Version 11 libXft 2.3.8 Xft(3)