Xft - X FreeType interface library


       Xft is a simple library which draws text and graphics:

       o   using information provided by the Fontconfig library,

       o   Xft converts font glyphs using the FreeType rasterizer, and

       o   displays the converted font data using the X Rendering Extension.

       This manual page barely scratches the surface of this library.


       #include <X11/Xft/Xft.h>


              is the major version number of Xft.

              is the minor version number of Xft.

              is the revision number of Xft.

              is  XFT_MAJOR  times  10000 (ten thousand), plus XFT_MINOR times
              100, plus XFT_REVISION.

              is an alias for XFT_VERSION.

       The following example illustrates how Xft's version constants might  be
             #if (XFT_VERSION >= 20107)
             (void) puts("Version 2.1.7 or later of the Xft library is in"
                         " use.");
             (void) printf("Insufficient version of Xft (%d.%d.%d) installed;
                           " need at least version 2.1.7.\n", XFT_MAJOR,


       Xft  datatypes  follow  a  naming  convention, prefixing all names with

From Xlib...

       Xlib datatypes do not follow a naming convention.  They are  documented
       in Xlib – C Language Interface.

       Xft  uses  these  names: Bool, Colormap, Display, Drawable, Pixmap, Re-
       gion, Visual, and XRectangle.

       Some datatypes are especially relevant to Xft:

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

            Declared  in <X11/Xutil.h> and <X11/Xregion.h>, a Region is an ar-
            bitrary set of pixel locations which Xlib can manipulate.   Inter-
            nally, a Region is represented by the union of an arbitrary number
            of rectangles.  Xlib maintains a rectangle which tells it the  ex-
            tent of this union.

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

From XRender...

       The X Render Extension library datatypes are inspired by Xlib, but lack
       the corresponding documentation.  Refer to the header file for details:


       or read the source code (which provides an outline of libXrender).

       Xft uses these names: Picture, XGlyphInfo, XRenderColor.

From Fontconfig...

       Fontconfig  datatypes  follow  a naming convention, prefixing all names
       with "Fc" which are documented in Fontconfig Developers Reference.

       Xft uses these Fontconfig names: FcBool, FcChar8,  FcChar16,  FcChar32,
       FcCharSet, FcEndian, FcFontSet, FcPattern, and FcResult.

From FreeType 2...

       FreeType  2  datatypes  follow a naming convention, prefixing all names
       with "FT_" which are documented in FreeType API Reference.

       Xft uses these names: FT_Face, FT_Library, and FT_UInt.

       FreeType 2 uses FT_UInt (an unsigned integer) to represent glyphs.


         typedef struct _XftFont {
                   int                  ascent;
                   int                  descent;
                   int                  height;
                   int                  max_advance_width;
                   FcCharSet           *charset;
                   FcPattern           *pattern;
         } XftFont;

       An XftFont is the primary data structure of interest to programmers us-
       ing  Xft; it contains general font metrics and pointers to the Fontcon-
       fig character set and pattern associated with the font.

       XftFonts are populated with any  of  XftFontOpen(),  XftFontOpenName(),
       XftFontOpenXlfd(),  XftFontOpenInfo(),  or  XftFontOpenPattern().  Xft-
       FontCopy() is used to duplicate XftFonts, and XftFontClose() is used to
       mark  an  XftFont as unused.  XftFonts are internally allocated, refer-
       ence-counted, and freed by Xft; the programmer does not ordinarily need
       to allocate or free storage for them.

       XftDrawGlyphs(),  the  XftDrawString*()  family, XftDrawCharSpec(), and
       XftDrawGlyphSpec() use XftFonts to render text to  an  XftDraw  object,
       which  may correspond to either a core X drawable or an X Rendering Ex-
       tension drawable.

       XftGlyphExtents() and the XftTextExtents*() family are used  to  deter-
       mine the extents (maximum dimensions) of an XftFont.

       An  XftFont's  glyph  or character coverage can be determined with Xft-
       FontCheckGlyph() or XftCharExists().  XftCharIndex() returns  the  Xft-
       Font-specific  character  index  corresponding to a given Unicode code-

       XftGlyphRender(), XftGlyphSpecRender(),  XftCharSpecRender(),  and  the
       XftTextRender*() family use XftFonts to draw into X Rendering Extension
       Picture structures.

       Note: XftDrawGlyphs(), the XftDrawString*() family,  XftDrawCharSpec(),
       and XftDrawGlyphSpec() provide a means of rendering fonts that is inde-
       pendent of the availability of the  X  Rendering  Extension  on  the  X


       is  an opaque object that stores information about a font.  XftFontInfo
       structures are created with XftFontInfoCreate(), freed with  XftFontIn-
       foDestroy(), and compared with XftFontInfoEqual().  XftFontInfo objects
       are internally allocated and freed by Xft; the programmer does not  or-
       dinarily need to allocate or free storage for them.

       Each  XftFontInfo  structure in use is associated with a unique identi-
       fier, which can be retrieved with XftFontInfoHash().  An XftFont can be
       opened based on XftFontInfo data with XftFontOpenInfo().


         typedef struct _XftColor {
                   unsigned long        pixel;
                   XRenderColor         color;
         } XftColor;

       An  XftColor  object  permits  text and other items to be rendered in a
       particular color (or the closest approximation offered by the X  visual
       in use).

       XftColorAllocName() and XftColorAllocValue() request a color allocation
       from the X server (if necessary) and initialize  the  members  of  Xft-
       Color.   XftColorFree()  instructs  the X server to free the color cur-
       rently allocated for an XftColor.

       Once an XftColor has been initialized,  XftDrawSrcPicture(),  XftDrawG-
       lyphs(),  the  XftDrawString*() family, XftDrawCharSpec(), XftDrawChar-
       FontSpec(),  XftDrawGlyphSpec(),   XftDrawGlyphFontSpec(),   and   Xft-
       DrawRect() may be used to draw various objects using it.


       is  an  opaque  object  which  holds information used to render to an X
       drawable using either the core protocol or the X Rendering extension.

       XftDraw objects are created with any of  XftDrawCreate()  (which  asso-
       ciates  an XftDraw with an existing X drawable), XftDrawCreateBitmap(),
       or XftDrawCreateAlpha(), and destroyed with  XftDrawDestroy().   The  X
       drawable   associated   with  an  XftDraw  can  be  changed  with  Xft-
       DrawChange().  XftDraw objects are internally allocated  and  freed  by
       Xft;  the programmer does not ordinarily need to allocate or free stor-
       age for them.

       The X Display, Drawable, Colormap, and Visual properties of an  XftDraw
       can  be  queried  with XftDrawDisplay(), XftDrawDrawable(), XftDrawCol-
       ormap(), and XftDrawVisual(), respectively.

       Several functions  use  XftDraw  objects:  XftDrawCharFontSpec(),  Xft-
       DrawCharSpec(),  XftDrawGlyphFontSpec(),  XftDrawGlyphSpec(), XftDrawG-
       lyphs(), XftDrawRect(),  XftDrawSetClip(),  XftDrawSetClipRectangles(),
       XftDrawSetSubwindowMode(), and the XftDrawString*() family.

       The  X  Rendering  Extension  Picture associated with an XftDraw is re-
       turned by XftDrawPicture(), and XftDrawSrcPicture().   It  is  used  by
       XftCharFontSpecRender(), XftCharSpecRender(), XftGlyphFontSpecRender(),
       XftGlyphRender(), XftGlyphSpecRender(), and the  XftTextRender*()  fam-


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

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


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

       XftCharFontSpec is used by XftCharFontSpecRender().


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

       XftGlyphSpec is used by XftDrawGlyphSpec().


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

       XftGlyphFontSpec  is  used  by  XftDrawGlyphFontSpec(),  and  XftGlyph-



       A typical application using Xft does not explicitly initialize the  li-
       brary.  That is usually done as a side-effect of opening a font.

       When  Xft  initializes,  it collects information about the display, and
       stores some of that information in a Fontconfig pattern (essentially  a
       collection  of  properties with typed values).  The calling application
       can modify that pattern to change the library's behavior.

       Not all of the collected information is stored in a pattern.   The  re-
       mainder  is stored in internal data structures.  Xft makes some of that
       available to the application via functions.

       Bool XftDefaultHasRender (
                      Display               *dpy);

              Obtain information about the display dpy if  not  done  already,
              and  return  true  if  Xft found that the display supports the X
              Render extension, and if it is able to find a suitable  XRender-
              PictFormat  (X  Render's  datatype  which is analogous to Xlib's
              Visual) on the display.

       Bool XftDefaultSet (
                      Display               *dpy,
                      FcPattern             *defaults);

              Obtain information about the display dpy if  not  done  already,
              and  set the Fontconfig pattern holding default properties which
              Xft will use for this display.

              Xft uses those properties initially to obtain these limits:

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

                      (maxunreffonts).  This is the maximum number of unrefer-
                      enced fonts (default: 16).

              Xft also uses  these  default  properties  in  XftDefaultSubsti-

       void XftDefaultSubstitute (
                      Display               *dpy,
                      int                    screen,
                      FcPattern             *pattern);

              Xft  fills  in missing properties in the given pattern using de-
              fault properties for the specified display dpy, e.g., as set  in

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

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

                      True  if  FreeType  should  use  autohinting   (default:

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

                      True if FT_GlyphSlot_Embolden() should be  used  to  em-
                      bolden a font (default: False).

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

                      Hinting style used when filling in properties to open  a
                      font (default: FC_HINT_FULL).

                      Parameter passed to FT_Library_SetLcdFilter() when load-
                      ing glyphs (default: FC_LCD_DEFAULT).

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

                      RGBA  value  used  when  filling in properties to open a
                      font (default: computed by  calling  XRenderQuerySubpix-

                      Scale used in Fontconfig (default: 1.0).

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

                      True  if  the  display  supports X Render extension (de-
                      fault: result from XftDefaultHasRender()).

       FcBool XftInit (
                      _Xconst char          *config);

              Initializes the Fontconfig library (calling FcInit()).

              The config parameter is unused.

              Xft does not deinitialize the  Fontconfig  library  when  it  is

       FcBool XftInitFtLibrary (void);

              Initializes  the FreeType library (calling FT_Init_FreeType() to
              create a library object) if it has not already been initialized.
              This  is  needed  before using the FreeType library to read font
              data from a file.

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

              Xft   does   not   discard   the  library  object  (e.g.,  using
              FT_Done_FreeType()) when it is done.

       int XftGetVersion (void);

              Return XftVersion, enabling an application to determine the  ac-
              tual version of Xft which is in use.

Opening and Matching Fonts

       XftFont *XftFontOpen (
                      Display               *dpy,
                      int                    screen,

              XftFontOpen  takes a list of pattern element triples of the form
              field, type, value (terminated with a NULL), matches  that  pat-
              tern  against  the available fonts, and opens the matching font,
              sizing it correctly for screen number  screen  on  display  dpy.
              Return the matched font, or NULL if no match is found.

             font = XftFontOpen (dpy, screen,
                                 XFT_FAMILY, XftTypeString, "charter",
                                 XFT_SIZE, XftTypeDouble, 12.0,

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

       XftFont *XftFontOpenName (
                      Display               *dpy,
                      int                    screen,
                      _Xconst char          *name);

              XftFontOpenName  behaves  as  XftFontOpen  does,  except that it
              takes a Fontconfig pattern string (which is passed to the  Font-
              config library's FcNameParse() function).

       XftFont *XftFontOpenXlfd (
                      Display               *dpy,
                      int                    screen,
                      _Xconst char          *xlfd)

              XftFontOpenXlfd  behaves  as  XftFontOpen  does,  except that it
              takes a string containing an X Logical Font Description  (XLFD),
              and uses the XftXlfdParse() function.

       FcPattern *XftFontMatch (
                      Display               *dpy,
                      int                    screen,
                      _Xconst FcPattern     *pattern,
                      FcResult              *result);

              Also used internally by the XftFontOpen* functions, XftFontMatch
              can also be used directly to determine the Fontconfig font  pat-
              tern resulting from an Xft font open request.

       FcPattern *XftXlfdParse (
                      _Xconst char          *xlfd_orig,
                      Bool                  ignore_scalable,
                      Bool                  complete);

              XftXlfdParse  parses  the xlfd_orig parameter according to the X
              Logical Font Description Conventions document, but ignores  some
              of the fields: setwidth_name, add_style_name, spacing, and aver-

              XftXlfdParse creates a Fontconfig pattern, setting the  property
              XFT_XLFD to the xlfd_orig value, and maps the collected informa-
              tion to Fontconfig properties.  Empty or "*" fields are ignored:

                      from foundry.

                      from family.

                      weight_name, defaulting to FC_WEIGHT_MEDIUM.

                      from slant, defaulting to FC_SLANT_ROMAN.

                      from point_size.

                      from pixel_size.  If point_size was set, as well as res-
                      olution_xand resolution_y, then the value is scaled con-
                      vert the font's height to points.

Families of Functions

       Xft provides groups of drawing functions which differ according to  the
       way  the  data is encoded, e.g., 8-bit (ISO-8859-1) versus UTF-8.  Here
       is a summary of these related functions:

       Encoding   XftDrawString*       XftTextExtents*       XftTextRender*
       8          XftDrawString8       XftTextExtents8       XftTextRender8
       16         XftDrawString16      XftTextExtents16      XftTextRender16
       16BE       XftDrawString16      XftTextExtents16      XftTextRender16BE
       16LE       XftDrawString16      XftTextExtents16      XftTextRender16LE
       32         XftDrawString32      XftTextExtents32      XftTextRender32
       32BE       XftDrawString32      XftTextExtents32      XftTextRender32BE
       32LE       XftDrawString32      XftTextExtents32      XftTextRender32LE
       UTF-8      XftDrawStringUtf8    XftTextExtentsUtf8    XftTextRenderUtf8
       UTF-16     XftDrawStringUtf16   XftTextExtentsUtf16   XftTextRenderUtf16

Determining Text Extents

       Xft provides several functions for determining the required height  and
       width  for  displaying a text-string.  After accounting for the offset,
       in cases where the string will be shifted  up,  down,  left  or  right,
       these numbers are referred to as text extents.

       void XftTextExtents8 (
                      Display               *dpy,
                      XftFont               *font,
                      _Xconst FcChar8       *string,
                      int                    len,
                      XGlyphInfo            *extents);

              XftTextExtents8  computes the pixel extents on display dpy of no
              more than len glyphs of a string consisting of eight-bit charac-
              ters when drawn with font, storing them in extents.

       void XftTextExtents16 (
                      Display               *dpy,
                      XftFont               *font,
                      _Xconst FcChar16      *string,
                      int                    len,
                      XGlyphInfo            *extents);

              XftTextExtents16 computes the pixel extents on display dpy of no
              more than len glyphs of a string consisting of sixteen-bit char-
              acters when drawn with font, storing them in extents.

       void XftTextExtents32 (
                      Display               *dpy,
                      XftFont               *font,
                      _Xconst FcChar32      *string,
                      int                    len,
                      XGlyphInfo            *extents);

              XftTextExtents32 computes the pixel extents on display dpy of no
              more than len glyphs of a string  consisting  of  thirty-two-bit
              characters when drawn with font, storing them in extents.

       void XftTextExtentsUtf8 (
                      Display               *dpy,
                      XftFont               *font,
                      _Xconst FcChar8       *string,
                      int                    len,
                      XGlyphInfo            *extents);

              XftTextExtentsUtf8  computes the pixel extents on display dpy of
              no more than len bytes of a UTF-8 encoded string when drawn with
              font, storing them in extents.

       void XftTextExtentsUtf16 (
                      Display               *dpy,
                      XftFont               *font,
                      _Xconst FcChar8       *string,
                      FcEndian               endian,
                      int                    len,
                      XGlyphInfo            *extents);

              XftTextExtentsUtf16 computes the pixel extents on display dpy of
              no more than len bytes of a UTF-16LE- or UTF-16BE-encoded string
              when  drawn  with font, storing them in extents.  The endianness
              of string must be specified in endian.

       void XftGlyphExtents (
                      Display               *dpy,
                      XftFont               *font,
                      _Xconst FT_UInt       *glyphs,
                      int                    nglyphs,
                      XGlyphInfo            *extents);

              Also used internally by the XftTextExtents*()  functions,  XftG-
              lyphExtents computes the pixel extents on display dpy of no more
              than nglyphs in the array glyphs drawn with font,  storing  them
              in extents.

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

Managing XftColor

       Bool XftColorAllocName (
                      Display               *dpy,
                      _Xconst Visual        *visual,
                      Colormap               cmap,
                      _Xconst char          *name,
                      XftColor              *result);

              Use  XAllocNamedColor()  to look up the named color name for the
              screen associated with the colormap cmap.

              o   If XAllocNamedColor() returns  nonzero,  XftColorAllocName()
                  fills in the resulting XftColor pixel field with the closest
                  color supported by the screen, as well  as  the  exact  red,
                  green and blue fields from the database, and returns True.

              o   If  XAllocNamedColor() returns zero, XftColorAllocName() re-
                  turns False, and does not update the XftColor referenced  by

              The visual parameter is unused.

       Bool XftColorAllocValue (
                      Display               *dpy,
                      Visual                *visual,
                      Colormap               cmap,
                      _Xconst XRenderColor  *color,
                      XftColor              *result);

              Allocate a color value:

              o   If  the visual class is TrueColor, XftColorAllocValue() sets
                  the pixel field in the XftColor referenced by  result  using
                  the red, green and blue fields from the color parameter.

              o   If  the  visual class is not TrueColor, XftColorAllocValue()
                  calls XAllocColor() to allocate an  entry  in  the  colormap
                  cmap.  which returns the pixel value of the color closest to
                  the specified RGB elements supported by the hardware.

                  If XAllocColor() succeeds XftColorAllocValue()  stores  that
                  pixel value in the XRenderColor referenced by result and re-
                  turns True.

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

       void XftColorFree (
                      Display               *dpy,
                      Visual                *visual,
                      Colormap               cmap,
                      XftColor              *color);

              If the visual class is not TrueColor, Xft calls XFreeColors() to
              free the entry from the colormap cmap whose pixel value  in  the
              color parameter was allocated by XftColorAllocName().

Managing XftDraw

       XftDraw *XftDrawCreate (
                      Display               *dpy,
                      Drawable               drawable,
                      Visual                *visual,
                      Colormap               colormap);

              XftDrawCreate  creates  a  structure  that can be used to render
              text and rectangles using the specified  drawable,  visual,  and
              colormap on display.

       XftDraw *XftDrawCreateBitmap (
                      Display               *dpy,
                      Pixmap                 bitmap);

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

       XftDraw * XftDrawCreateAlpha (
                      Display               *dpy,
                      Pixmap                 pixmap,
                      int                    depth);

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

       void XftDrawChange (
                      XftDraw               *draw,
                      Drawable               drawable);

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

       Display *XftDrawDisplay (
                      XftDraw               *draw);

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

       Drawable XftDrawDrawable (
                      XftDraw               *draw);

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

       Colormap XftDrawColormap (
                      XftDraw               *draw);

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

       Visual *XftDrawVisual (
                      XftDraw               *draw);

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

       Picture XftDrawPicture (
                      XftDraw               *draw);

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

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

       Picture XftDrawSrcPicture (
                      XftDraw               *draw,
                      _Xconst XftColor      *color);

              Return an X Render Picture object, which is used  for  rendering
              glyphs,  e.g.,  with  XftGlyphRender(), XftGlyphSpecRender(), or
              XftGlyphFontSpecRender(),  by   XftDrawGlyphs(),   XftDrawGlyph-
              Spec(), XftDrawGlyphFontSpec(), respectively.

              If  the  X server does not support the X Render extension, those
              functions use XftGlyphCore(), XftGlyphSpecCore(),  or  XftGlyph-

       void XftDrawDestroy (
                      XftDraw               *draw);

              XftDrawDestroy  destroys draw (created by one of the XftDrawCre-
              ate*() functions) and frees the memory that  was  allocated  for

       Bool XftDrawSetClip (
                      XftDraw               *draw,
                      Region                 r);

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

              o   If the Region parameter r is not null, Xft creates a new Re-
                  gion (to copy the parameter),

              o   Xft destroys any existing clipping region.

              o   Xft  sets  the  clip_type for the draw parameter to XftClip-
                  TypeRegion if the r parameter was not  null.   Otherwise  it
                  sets the clip_type to XftClipTypeNone.

              o   Finally,  Xft updates clipping for existing objects, updates
                  the clip_mask for its X Render Picture object and  sets  the
                  clipping-mask  in  the  graphic context (GC) associated with
                  the XftDraw parameter.

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

       Bool XftDrawSetClipRectangles (
                      XftDraw               *draw,
                      int                    xOrigin,
                      int                    yOrigin,
                      _Xconst XRectangle    *rects,
                      int                    n);

              Like XftDrawSetClip(), XftDrawSetClipRectangles() sets up  clip-
              ping  for  the  given XftDraw parameter draw but uses a set of n
              rectangles (the rects parameter) which could  be  used  to  con-
              struct a Region .

              Xft  sets  the  clip_type  for draw to XftClipTypeRectangles and
              uses XSetClipRectangles() for core (X11) clipping  and  XRender-
              SetPictureClipRectangles() for X Render clipping.

       void XftDrawSetSubwindowMode (
                      XftDraw               *draw,
                      int                    mode);

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

              o   For  ClipByChildren, both source and destination windows are
                  additionally clipped by all viewable InputOutput children.

              o   For IncludeInferiors, neither source nor destination  window
                  is clipped by inferiors.  This will result in including sub-
                  window contents in the source and drawing through  subwindow
                  boundaries of the destination.

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

Drawing Strings

       void XftDrawString8 (
                      XftDraw               *d,
                      _Xconst XftColor      *color,
                      XftFont               *font,
                      int                    x,
                      int                    y,
                      _Xconst FcChar8       *string,
                      int                    len);

              XftDrawString8 draws no more than len glyphs of  string  to  Xft
              drawable d using font in color at position x, y.

Drawing Other Things

       void XftDrawRect (
                      XftDraw               *d,
                      _Xconst XftColor      *color,
                      int                    x,
                      int                    y,
                      unsigned int           width,
                      unsigned int           height);

              XftDrawRect  draws  a  solid  rectangle  of the specified color,
              width, and height at position x, y to Xft drawable d.

       void XftCharFontSpecRender (
                      Display               *dpy,
                      int                    op,
                      Picture                src,
                      Picture                dst,
                      int                    srcx,
                      int                    srcy,
                      _Xconst XftCharFontSpec*chars,
                      int                    len);

              XftCharFontSpecRender()  converts  the  chars   parameter   from
              XftCharFontSpec to XftGlyphFontSpec, passing the converted array
              along  with  the  other  parameters   unchanged   to   XftGlyph-
              FontSpecRender() to render the data.

       void XftDrawGlyphFontSpec (
                      XftDraw               *draw,
                      _Xconst XftColor      *color,
                      _Xconst XftGlyphFontSpec*glyphs,
                      int                    len);

              Draw a list of glyphs associated with fonts at specified coordi-
              nates, passed as an array of len XftGlyphFontSpec structures via
              the  parameter  glyphs.   All  of the glyphs are drawn using the
              color specified in the color parameter.

              For each entry in the glyphs array:

              o   If the associated font uses the X Render extension, then Xft
                  uses  XftGlyphFontSpecRender()  to  draw  the glyph, using a
                  Picture obtained from calling XftDrawSrcPicture () with  the
                  draw and color parameters.

              o   Otherwise, Xft provides an analogous feature using Xlib.

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

              This involves several steps:

              o   First,  Xft  ensures that the glyphs array is complete using
                  XftFontCheckGlyph() and loading any missing glyphs with Xft-

              o   Then  Xft  examines  the  glyphs to find the maximum Unicode
                  value.  That determines the encoding size, i.e., the width.

              o   Then, for each glyph, Xft checks if  its  Unicode  value  is
                  handled by the corresponding font.  If not, the value is set
                  to zero (0), to ignore it.  While doing this, Xft  also  re-
                  members  which was the first font used, and computes the po-
                  sition at which each glyph will be drawn.

              o   Xft then constructs an equivalent array  of  glyphs  in  the
                  format expected by the X Render library.

              o   Finally,  XftGlyphFontSpecRender()  uses the X Render exten-
                  sion to draw the glyphs, with the appropriate XRenderCompos-
                  iteText*()  function  according  to  the width, and discards
                  temporary data.

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

Manipulating patterns

       FcFontSet *XftListFonts (
                      Display               *dpy,
                      int                    screen,

              Xft   uses   FcPatternVapBuild()  and  FcObjectSetVapBuild()  to
              process the variable-length parameter list, and FcFontList()  to
              obtain  a list of matching Fontconfig patterns, which it returns
              to the caller.  The caller can dispose of the return value using

       FcPattern *XftNameParse (
                      _Xconst char          *name);

              Xft  uses  Fontconfig to parse the name, passing the name to Fc-
              NameParse(), returning the result.

       FcBool XftNameUnparse (
                      FcPattern             *pat,
                      char                  *dest,
                      int                    len);

              Like XfgNameParse(), Xft uses Fontconfig.  In this case, it uses
              FcNameUnparse(),  which  converts  the  pattern  pat back into a
              string that can be parsed.  XftNameUnparse() stores  the  result
              via  the caller's pointer dest, but checks first if it will fit,
              using the len parameter.  If it fits, Xft copies the string  and
              returns FcTrue, otherwise it returns FcFalse.

Manipulating Font data

       void XftFontLoadGlyphs (
                      Display               *dpy,
                      XftFont               *pub,
                      FcBool                 need_bitmaps,
                      _Xconst FT_UInt       *glyphs,
                      int                    nglyph);

              Using  FT_Load_Glyph(), load nglyphs for the glyph indices (Uni-
              code values) listed in the array glyphs from the given font pub.

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

       void XftFontUnloadGlyphs (
                      Display               *dpy,
                      XftFont               *pub,
                      _Xconst FT_UInt       *glyphs,
                      int                    nglyph);

              Discards  data for up to nglyph glyphs whose glyph indices (Uni-
              code values) are listed in the array glyphs for the  given  font
              pub.   If  the  glyphs were added to the X Render extension, Xft
              removes those using XRenderFreeGlyphs().  Xft keeps track of the
              amount  of memory used for glyphs, and updates the usage associ-
              ated with the display dpy.

       FT_Face XftLockFace (
                      XftFont               *pub);

              If no FreeType 2 "face" (in-memory  representation  of  a  given
              typeface  in  a  given style) has been created for the pub font,
              create one using  FT_New_Face().   Face-locks  are  a  reference
              count  used  by Xft to ensure that only one face is created, and
              that it is retained until the font is no longer used.

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

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

       void XftUnlockFace (
                      XftFont               *pub);

              Decrements the reference count for the FreeType 2 "face" associ-
              ated with the font.

              FT_Face objects are deallocated using FT_Done_Face().  Xft  does
              this  in XftFontInfoDestroy() and when cleaning up on failure in
              XftFontInfoCreate() and XftFontOpenPattern().


       Xft reads the environment variable XFT_DEBUG and converts  that  to  an
       integer.   Each bit in the resulting value tells Xft to print debugging
       information to the standard output:

       1    font-opening

       2    additional font-matching and opening (verbose)

       4    shows details about the XRenderPictFormat which will be used.

       8    shows the string which XftDrawString8() will draw.

       16   shows which font-ids are matched.

       32   shows useful information about the glyphs which will be drawn

       64   shows an ASCII-art representation of the glyphs.

       128  shows details about the memory-cache management

       256  shows details about managing glyph cached-memory

       512  shows a report on memory-usage


       As of version 2 (May 2002), Xft became relatively stable.   It  is  ex-
       pected to retain source and binary compatibility in future releases.

       Xft  provides  a compatibility interface to its previous major version,
       Xft 1.x, described below.

Xft 1.x Header File

       #include <X11/Xft/XftCompat.h>

Xft 1.x Data Types

              holds a set of names with  associated  value  lists;  each  name
              refers  to a property of a font.  XftPatterns are used as inputs
              to the matching code as well as holding information  about  spe-
              cific fonts.

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

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


       Keith Packard


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

X Version 11                     libXft 2.3.5                           Xft(3)