1Xft(3)                           X Version 11                           Xft(3)
2
3
4

NAME

6       Xft - X FreeType interface library
7

DESCRIPTION

9       Xft is a simple library which draws text and graphics:
10
11       •   using information provided by the Fontconfig library,
12
13Xft converts font glyphs using the FreeType rasterizer, and
14
15       •   displays the converted font data using the X Rendering Extension.
16
17       This manual page barely scratches the surface of this library.
18

HEADER FILE

20       #include <X11/Xft/Xft.h>
21

CONSTANTS

23       XFT_MAJOR
24              is the major version number of Xft.
25
26       XFT_MINOR
27              is the minor version number of Xft.
28
29       XFT_REVISION
30              is the revision number of Xft.
31
32       XFT_VERSION
33              is  XFT_MAJOR  times  10000 (ten thousand), plus XFT_MINOR times
34              100, plus XFT_REVISION.
35
36       XftVersion
37              is an alias for XFT_VERSION.
38
39       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

DATA TYPES

52       Xft  datatypes  follow  a  naming  convention, prefixing all names with
53       “Xft”
54
55   From Xlib...
56       Xlib datatypes do not follow a naming convention.  They are  documented
57       in Xlib - C Language Interface.
58
59       Xft  uses  these  names: Bool, Colormap, Display, Drawable, Pixmap, Re‐
60       gion, Visual, and XRectangle.
61
62       Some datatypes are especially relevant to Xft:
63
64       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
72       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
79       Visual
80            Declared  in  <X11/Xutil.h>,  this  structure contains information
81            about the possible color mapping.
82
83   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
87              <X11/extensions/Xrender.h>
88
89       or read the source code (which provides an outline of libXrender).
90
91       Xft uses these names: Picture, XGlyphInfo, XRenderColor.
92
93   From Fontconfig...
94       Fontconfig  datatypes  follow  a naming convention, prefixing all names
95       with “Fc” which are documented in Fontconfig Developers Reference.
96
97       Xft uses these Fontconfig names: FcBool, FcChar8,  FcChar16,  FcChar32,
98       FcCharSet, FcEndian, FcFontSet, FcPattern, and FcResult.
99
100   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
104       Xft uses these names: FT_Face, FT_Library, and FT_UInt.
105
106       FreeType 2 uses FT_UInt (an unsigned integer) to represent glyphs.
107
108   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
118       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
122       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
129       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
134       XftGlyphExtents() and the XftTextExtents*() family are used  to  deter‐
135       mine the extents (maximum dimensions) of an XftFont.
136
137       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
142       XftGlyphRender(), XftGlyphSpecRender(),  XftCharSpecRender(),  and  the
143       XftTextRender*() family use XftFonts to draw into X Rendering Extension
144       Picture structures.
145
146       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
151   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
158       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
162   XftColor
163         typedef struct _XftColor {
164                   unsigned long        pixel;
165                   XRenderColor         color;
166         } XftColor;
167
168       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
172       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
177       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
182   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
186       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
194       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
198       Several functions  use  XftDraw  objects:  XftDrawCharFontSpec(),  Xft‐
199       DrawCharSpec(),  XftDrawGlyphFontSpec(),  XftDrawGlyphSpec(), XftDrawG‐
200       lyphs(), XftDrawRect(),  XftDrawSetClip(),  XftDrawSetClipRectangles(),
201       XftDrawSetSubwindowMode(), and the XftDrawString*() family.
202
203       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
209   XftCharSpec
210         typedef struct _XftCharSpec {
211                   FcChar32             ucs4;
212                   short                x;
213                   short                y;
214         } XftCharSpec;
215
216       XftCharSpec is used by XftDrawCharSpec(), and XftCharSpecRender().
217
218   XftCharFontSpec
219         typedef struct _XftCharFontSpec {
220                   XftFont             *font;
221                   FcChar32             ucs4;
222                   short                x;
223                   short                y;
224         } XftCharFontSpec;
225
226       XftCharFontSpec is used by XftCharFontSpecRender().
227
228   XftGlyphSpec
229         typedef struct _XftGlyphSpec {
230                   FT_UInt               glyph;
231                   short                 x;
232                   short                 y;
233         } XftGlyphSpec;
234
235       XftGlyphSpec is used by XftDrawGlyphSpec().
236
237   XftGlyphFontSpec
238         typedef struct _XftGlyphFontSpec {
239                   XftFont             *font;
240                   FT_UInt              glyph;
241                   short                x;
242                   short                y;
243         } XftGlyphFontSpec;
244
245       XftGlyphFontSpec  is  used  by  XftDrawGlyphFontSpec(),  and  XftGlyph‐
246       FontSpecRender().
247

FUNCTIONS

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
253       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
258       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
262       Bool XftDefaultHasRender (
263                      Display               *dpy);
264
265              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
271       Bool XftDefaultSet (
272                      Display               *dpy,
273                      FcPattern             *defaults);
274
275              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
279              Xft uses those properties initially to obtain these limits:
280
281                 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
285                 XFT_MAX_UNREF_FONTS
286                      (maxunreffonts).  This is the maximum number of unrefer‐
287                      enced fonts (default: 16).
288
289                 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
295              Xft  also  uses  these  default  properties in XftDefaultSubsti‐
296              tute().
297
298       void XftDefaultSubstitute (
299                      Display               *dpy,
300                      int                    screen,
301                      FcPattern             *pattern);
302
303              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
307              Typical Xft applications use this function  to  help  Fontconfig
308              choose a suitable font.  These properties are substituted before
309              calling FcDefaultSubstitute():
310
311                 FC_ANTIALIAS
312                      True  if  FreeType  should  use  antialiasing  (default:
313                      False).  (default: True).
314
315                 FC_AUTOHINT
316                      True   if  FreeType  should  use  autohinting  (default:
317                      False).
318
319                 FC_DPI
320                      Dots/inch used for resolution  (default:  computed  from
321                      the display height).
322
323                 FC_EMBOLDEN
324                      True  if  FT_GlyphSlot_Embolden()  should be used to em‐
325                      bolden a font (default: False).
326
327                 FC_HINTING
328                      True if hinting should be used when filling  in  proper‐
329                      ties to open a font (default: True).
330
331                 FC_HINT_STYLE
332                      Hinting  style used when filling in properties to open a
333                      font (default: FC_HINT_FULL).
334
335                 FC_LCD_FILTER
336                      Parameter passed to FT_Library_SetLcdFilter() when load‐
337                      ing glyphs (default: FC_LCD_DEFAULT).
338
339                 FC_MINSPACE
340                      Minimum  space  value used when filling in properties to
341                      open a font (default: False).
342
343                 FC_RGBA
344                      RGBA value used when filling in  properties  to  open  a
345                      font  (default:  computed by calling XRenderQuerySubpix‐
346                      elOrder()).
347
348                 FC_SCALE
349                      Scale used in Fontconfig (default: 1.0).
350
351                 XFT_MAX_GLYPH_MEMORY
352                      Maximum memory for one font (default: 1024*1024).
353
354                 XFT_RENDER
355                      True if the display supports  X  Render  extension  (de‐
356                      fault: result from XftDefaultHasRender()).
357
358       FcBool XftInit (
359                      _Xconst char          *config);
360
361              Initializes the Fontconfig library (calling FcInit()).
362
363              The config parameter is unused.
364
365              Xft  does  not  deinitialize  the  Fontconfig library when it is
366              done.
367
368       FcBool XftInitFtLibrary (void);
369
370              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
375              Xft  calls XftInitFtLibrary() internally via XftFontInfoCreate()
376              and XftFontOpenPattern().
377
378              Xft  does  not  discard  the   library   object   (e.g.,   using
379              FT_Done_FreeType()) when it is done.
380
381       int XftGetVersion (void);
382
383              Return  XftVersion, enabling an application to determine the ac‐
384              tual version of Xft which is in use.
385
386   Opening and Matching Fonts
387       XftFont *XftFontOpen (
388                      Display               *dpy,
389                      int                    screen,
390                      ...);
391
392              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
398       Example:
399             font = XftFontOpen (dpy, screen,
400                                 XFT_FAMILY, XftTypeString, "charter",
401                                 XFT_SIZE, XftTypeDouble, 12.0,
402                                 NULL);
403
404              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
408       XftFont *XftFontOpenName (
409                      Display               *dpy,
410                      int                    screen,
411                      _Xconst char          *name);
412
413              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
417       XftFont *XftFontOpenXlfd (
418                      Display               *dpy,
419                      int                    screen,
420                      _Xconst char          *xlfd)
421
422              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
426       FcPattern *XftFontMatch (
427                      Display               *dpy,
428                      int                    screen,
429                      _Xconst FcPattern     *pattern,
430                      FcResult              *result);
431
432              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
436       FcPattern *XftXlfdParse (
437                      _Xconst char          *xlfd_orig,
438                      Bool                  ignore_scalable,
439                      Bool                  complete);
440
441              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
446              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
450                 FC_FOUNDRY
451                      from foundry.
452
453                 FC_FAMILY
454                      from family.
455
456                 FC_WEIGHT
457                      weight_name, defaulting to FC_WEIGHT_MEDIUM.
458
459                 FC_SLANT
460                      from slant, defaulting to FC_SLANT_ROMAN.
461
462                 FC_SIZE
463                      from point_size.
464
465                 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
470   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
475       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
487   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
493       void XftTextExtents8 (
494                      Display               *dpy,
495                      XftFont               *font,
496                      _Xconst FcChar8       *string,
497                      int                    len,
498                      XGlyphInfo            *extents);
499
500              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
504       void XftTextExtents16 (
505                      Display               *dpy,
506                      XftFont               *font,
507                      _Xconst FcChar16      *string,
508                      int                    len,
509                      XGlyphInfo            *extents);
510
511              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
515       void XftTextExtents32 (
516                      Display               *dpy,
517                      XftFont               *font,
518                      _Xconst FcChar32      *string,
519                      int                    len,
520                      XGlyphInfo            *extents);
521
522              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
526       void XftTextExtentsUtf8 (
527                      Display               *dpy,
528                      XftFont               *font,
529                      _Xconst FcChar8       *string,
530                      int                    len,
531                      XGlyphInfo            *extents);
532
533              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
537       void XftTextExtentsUtf16 (
538                      Display               *dpy,
539                      XftFont               *font,
540                      _Xconst FcChar8       *string,
541                      FcEndian               endian,
542                      int                    len,
543                      XGlyphInfo            *extents);
544
545              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
550       void XftGlyphExtents (
551                      Display               *dpy,
552                      XftFont               *font,
553                      _Xconst FT_UInt       *glyphs,
554                      int                    nglyphs,
555                      XGlyphInfo            *extents);
556
557              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
562              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
566   Managing XftColor
567       Bool XftColorAllocName (
568                      Display               *dpy,
569                      _Xconst Visual        *visual,
570                      Colormap               cmap,
571                      _Xconst char          *name,
572                      XftColor              *result);
573
574              Use XAllocNamedColor() to look up the named color name  for  the
575              screen associated with the colormap cmap.
576
577              •   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
582              •   If XAllocNamedColor() returns zero, XftColorAllocName()  re‐
583                  turns  False, and does not update the XftColor referenced by
584                  result.
585
586              The visual parameter is unused.
587
588       Bool XftColorAllocValue (
589                      Display               *dpy,
590                      Visual                *visual,
591                      Colormap               cmap,
592                      _Xconst XRenderColor  *color,
593                      XftColor              *result);
594
595              Allocate a color value:
596
597              •   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
601              •   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
606                  If  XAllocColor()  succeeds XftColorAllocValue() stores that
607                  pixel value in the XRenderColor referenced by result and re‐
608                  turns True.
609
610                  If  XAllocColor()  fails, XftColorAllocValue() returns False
611                  and does not modify the result.
612
613       void XftColorFree (
614                      Display               *dpy,
615                      Visual                *visual,
616                      Colormap               cmap,
617                      XftColor              *color);
618
619              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
623   Managing XftDraw
624       XftDraw *XftDrawCreate (
625                      Display               *dpy,
626                      Drawable               drawable,
627                      Visual                *visual,
628                      Colormap               colormap);
629
630              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
634       XftDraw *XftDrawCreateBitmap (
635                      Display               *dpy,
636                      Pixmap                 bitmap);
637
638              XftDrawCreateBitmap behaves as XftDrawCreate(), except  that  it
639              uses an X pixmap of color depth 1 instead of an X drawable.
640
641       XftDraw * XftDrawCreateAlpha (
642                      Display               *dpy,
643                      Pixmap                 pixmap,
644                      int                    depth);
645
646              XftDrawCreateAlpha  behaves  as  XftDrawCreate(), except that it
647              uses an X pixmap of color depth depth instead of an X drawable.
648
649       void XftDrawChange (
650                      XftDraw               *draw,
651                      Drawable               drawable);
652
653              XftDrawChange changes the X drawable association of the existing
654              Xft draw object draw from its current value to drawable.
655
656       Display *XftDrawDisplay (
657                      XftDraw               *draw);
658
659              XftDrawDisplay  returns a pointer to the display associated with
660              the Xft draw object draw.
661
662       Drawable XftDrawDrawable (
663                      XftDraw               *draw);
664
665              XftDrawDrawable returns the X drawable associated with  the  Xft
666              draw object draw.
667
668       Colormap XftDrawColormap (
669                      XftDraw               *draw);
670
671              XftDrawColormap()  returns  the colormap associated with the Xft
672              draw object draw.
673
674       Visual *XftDrawVisual (
675                      XftDraw               *draw);
676
677              XftDrawVisual returns a pointer to the  visual  associated  with
678              the Xft draw object draw.
679
680       Picture XftDrawPicture (
681                      XftDraw               *draw);
682
683              XftDrawPicture  returns the picture associated with the Xft draw
684              object draw.
685
686              If the the X server does not support the X Rendering  Extension,
687              0 is returned.
688
689       Picture XftDrawSrcPicture (
690                      XftDraw               *draw,
691                      _Xconst XftColor      *color);
692
693              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
698              If the X server does not support the X Render  extension,  those
699              functions  use  XftGlyphCore(), XftGlyphSpecCore(), or XftGlyph‐
700              FontSpecCore().
701
702       void XftDrawDestroy (
703                      XftDraw               *draw);
704
705              XftDrawDestroy destroys draw (created by one of the  XftDrawCre‐
706              ate*()  functions)  and  frees the memory that was allocated for
707              it.
708
709       Bool XftDrawSetClip (
710                      XftDraw               *draw,
711                      Region                 r);
712
713              Set up clipping for the given XftDraw  parameter  draw  starting
714              with a Region:
715
716              •   If the Region parameter r is not null, Xft creates a new Re‐
717                  gion (to copy the parameter),
718
719Xft destroys any existing clipping region.
720
721Xft 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
725              •   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
730              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
734       Bool XftDrawSetClipRectangles (
735                      XftDraw               *draw,
736                      int                    xOrigin,
737                      int                    yOrigin,
738                      _Xconst XRectangle    *rects,
739                      int                    n);
740
741              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
746              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
750       void XftDrawSetSubwindowMode (
751                      XftDraw               *draw,
752                      int                    mode);
753
754              Sets the subwindow-mode for the given  XftDraw  parameter  draw.
755              The mode can be either ClipByChildren (the default), or Include‐
756              Inferiors:
757
758              •   For ClipByChildren, both source and destination windows  are
759                  additionally clipped by all viewable InputOutput children.
760
761              •   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
766              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
771   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
781              XftDrawString8  draws  no  more than len glyphs of string to Xft
782              drawable d using font in color at position x, y.
783
784   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
793              XftDrawRect draws a solid  rectangle  of  the  specified  color,
794              width, and height at position x, y to Xft drawable d.
795
796       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
806              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
811       void XftDrawGlyphFontSpec (
812                      XftDraw               *draw,
813                      _Xconst XftColor      *color,
814                      _Xconst XftGlyphFontSpec*glyphs,
815                      int                    len);
816
817              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
822              For each entry in the glyphs array:
823
824              •   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
829              •   Otherwise, Xft provides an analogous feature using Xlib.
830
831       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
841              This involves several steps:
842
843              •   First, Xft ensures that the glyphs array is  complete  using
844                  XftFontCheckGlyph() and loading any missing glyphs with Xft‐
845                  FontLoadGlyphs().
846
847              •   Then Xft examines the glyphs to  find  the  maximum  Unicode
848                  value.  That determines the encoding size, i.e., the width.
849
850              •   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
856Xft  then  constructs  an  equivalent array of glyphs in the
857                  format expected by the X Render library.
858
859              •   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
864                  The  op, dst, src, srcx, and srcy parameters are used as de‐
865                  scribed in the documentation for the X Render library.
866
867   Manipulating patterns
868       FcFontSet *XftListFonts (
869                      Display               *dpy,
870                      int                    screen,
871                      ...);
872
873              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
879       FcPattern *XftNameParse (
880                      _Xconst char          *name);
881
882              Xft uses Fontconfig to parse the name, passing the name  to  Fc‐
883              NameParse(), returning the result.
884
885       FcBool XftNameUnparse (
886                      FcPattern             *pat,
887                      char                  *dest,
888                      int                    len);
889
890              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
897   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
905              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
908              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
915       void XftFontUnloadGlyphs (
916                      Display               *dpy,
917                      XftFont               *pub,
918                      _Xconst FT_UInt       *glyphs,
919                      int                    nglyph);
920
921              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
928       FT_Face XftLockFace (
929                      XftFont               *pub);
930
931              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
937              Face-locking is used directly in XftCharIndex() and XftFontLoad‐
938              Glyphs(), which in turn are used in many functions of Xft.
939
940              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
946       void XftUnlockFace (
947                      XftFont               *pub);
948
949              Decrements the reference count for the FreeType 2 “face” associ‐
950              ated with the font.
951
952              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

DEBUGGING

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
961       1    font-opening
962
963       2    additional font-matching and opening (verbose)
964
965       4    shows details about the XRenderPictFormat which will be used.
966
967       8    shows the string which XftDrawString8() will draw.
968
969       16   shows which font-ids are matched.
970
971       32   shows useful information about the glyphs which will be drawn
972
973       64   shows an ASCII-art representation of the glyphs.
974
975       128  shows details about the memory-cache management
976
977       256  shows details about managing glyph cached-memory
978
979       512  shows a report on memory-usage
980
981       1024 shows details on extended management of glyph cached-memory
982

COMPATIBILITY

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
987       Xft provides a compatibility interface to its previous  major  version,
988       Xft 1.x, described below.
989
990   Xft 1.x Header File
991       #include <X11/Xft/XftCompat.h>
992
993   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
1000       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
1005       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

AUTHOR

1011       Keith Packard
1012       Thomas E. Dickey (performance improvements)
1013

SEE ALSO

1015       Fontconfig Developers Reference
1016       FreeType API Reference
1017       Xlib - C Language Interface
1018       X Logical Font Description Conventions
1019
1020
1021
1022X Version 11                     libXft 2.3.8                           Xft(3)
Impressum