1Xft(3)                     Library Functions Manual                     Xft(3)
2
3
4

NAME

6        Xft - X FreeType interface library
7

DESCRIPTION

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

HEADER FILE

14       #include <X11/Xft/Xft.h>
15

CONSTANTS

17       XFT_MAJOR
18              is the major version number of Xft.
19
20       XFT_MINOR
21              is the minor version number of Xft.
22
23       XFT_REVISION
24              is the revision number of Xft.
25
26       XFT_VERSION
27              is  XFT_MAJOR  times  10000 (ten thousand), plus XFT_MINOR times
28              100, plus XFT_REVISION.
29
30       XftVersion
31              is an alias for XFT_VERSION.
32
33       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

DATA TYPES

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
61              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
69              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
74              XftGlyphExtents() and the XftTextExtents*() family are  used  to
75              determine the extents (maximum dimensions) of an XftFont.
76
77              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
82              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
89       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
97              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
102       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
112              XftColorAllocName() and  XftColorAllocValue()  request  a  color
113              allocation  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
117              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
121              objects using it.
122
123       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
126              extension.
127
128              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
134              allocate or free storage for them.
135
136              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
139              Extension Picture associated with an XftDraw is returned by Xft‐
140              DrawPicture().
141
142       XftCharSpec
143              typedef struct _XftCharSpec {
144                  FcChar32    ucs4;
145                  short       x;
146                  short       y;
147              } XftCharSpec;
148
149              The FcChar32 data type is defined by the Fontconfig library.
150
151       XftCharFontSpec
152              typedef struct _XftCharFontSpec {
153                  XftFont     *font;
154                  FcChar32    ucs4;
155                  short       x;
156                  short       y;
157              } XftCharFontSpec;
158
159              The FcChar32 data type is defined by the Fontconfig library.
160
161       XftGlyphSpec
162              typedef struct _XftGlyphSpec {
163                  FT_UInt     glyph;
164                  short       x;
165                  short       y;
166              } XftGlyphSpec;
167
168              The FT_UInt data type is defined by the FreeType library.
169
170       XftGlyphFontSpec
171              typedef struct _XftGlyphFontSpec {
172                  XftFont     *font;
173                  FT_UInt     glyph;
174                  short       x;
175                  short       y;
176              } XftGlyphFontSpec;
177
178              The FT_UInt data type is defined by the FreeType library.
179

FUNCTIONS

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
192       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
201       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
209       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
216       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
226   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
236       defined by the Fontconfig library, and  the  XGlyphInfo  data  type  is
237       defined by the X Rendering Extension library.
238
239       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
249       defined by the X Rendering Extension library.
250
251       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
263       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
274       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
288       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
300   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
311       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
318       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
326       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
332       Display *
333       XftDrawDisplay (XftDraw *draw);
334       XftDrawDisplay returns a pointer to the display associated with the Xft
335       draw object draw.
336
337       Drawable
338       XftDrawDrawable (XftDraw *draw);
339       XftDrawDrawable returns the X drawable associated  with  the  Xft  draw
340       object draw.
341
342       Colormap
343       XftDrawColormap (XftDraw *draw);
344       XftDrawColormap  returns  the  colormap  associatied  with the Xft draw
345       object draw.
346
347       Visual *
348       XftDrawVisual (XftDraw *draw);
349       XftDrawVisual returns a pointer to the visual associated with  the  Xft
350       draw object draw.
351
352       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
358       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
364       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
369       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
380       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

COMPATIBILITY

391       As  of  version  2, Xft has become relatively stable and is expected to
392       retain source and binary compatibility in future releases.
393
394       Xft does provide a compatibility interface to its previous  major  ver‐
395       sion, Xft 1.x, described below.
396
397   Xft 1.x Compatibility Header File
398       #include <X11/Xft/XftCompat.h>
399
400   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
407       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
412       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

AUTHOR

418       Keith Packard
419

SEE ALSO

421       Fontconfig Developers Reference
422       FreeType API Reference
423       Xlib - C Language Interface
424
425
426
427X Version 11                     libXft 2.3.3                           Xft(3)
Impressum