packages icon



 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



 NAME
       Xft - X FreeType interface library

 DESCRIPTION
      Xft is a simple library designed to interface the FreeType rasterizer
      with the X Rendering Extension.  This manual page barely scratches the
      surface of this library.

 HEADER FILE
      #include <X11/Xft/Xft.h>

 CONSTANTS
      XFT_MAJOR
           is the major version number of Xft.

      XFT_MINOR
           is the minor version number of Xft.

      XFT_REVISION
           is the revision number of Xft.

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

      XftVersion
           is an alias for XFT_VERSION.

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

 DATA TYPES
      XftFont
           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



                                    - 1 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



           programmers using Xft; it contains general font metrics and
           pointers to the Fontconfig character set and pattern associated
           with the font.  The FcCharSet and FcPattern data types are
           defined by the Fontconfig library.

      XftFonts
           are populated with any of XftFontOpen(), XftFontOpenName(),
           XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPattern().
           XftFontCopy() is used to duplicate XftFonts, and XftFontClose()
           is used to mark an XftFont as unused.  XftFonts are internally
           allocated, reference-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 Extension drawable.

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

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

      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
           independent of the availability of the X Rendering Extension on
           the X server.

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

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





                                    - 2 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



      XftColor
           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).  The XRenderColor data type is defined by the X
           Render Extension library.

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

      One an
           XftColor has been initialized, XftDrawSrcPicture(),
           XftDrawGlyphs(), the XftDrawString*() family, XftDrawCharSpec(),
           XftDrawCharFontSpec(), XftDrawGlyphSpec(),
           XftDrawGlyphFontSpec(), and XftDrawRect() may be used to draw
           various objects using it.

      XftDraw
           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 associates
           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
           XftDrawChange().  XftDraws are internally allocated and freed by
           Xft; the programmer does not ordinarily need to allocate or free
           storage for them.

      The X
           Display, Drawable, Colormap, and Visual of an XftDraw can be
           queried with XftDrawDisplay(), XftDrawDrawable(),
           XftDrawColormap(), and XftDrawVisual(), respectively.  The X
           Rendering Extension Picture associated with an XftDraw is
           returned by XftDrawPicture().

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




                                    - 3 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



      The  FcChar32 data type is defined by the Fontconfig library.

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

      The  FcChar32 data type is defined by the Fontconfig library.

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

      The  FT_UInt data type is defined by the FreeType library.

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

      The  FT_UInt data type is defined by the FreeType library.

 FUNCTIONS
    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 pattern against the
      available fonts, and opens the matching font, sizing it correctly for
      screen number screen on display dpy.  The Display data type is defined
      by the X11 library.  Returns NULL if no match is found.

      Example:
          font = XftFontOpen (dpy, screen,
                              XFT_FAMILY, XftTypeString, "charter",
                              XFT_SIZE, XftTypeDouble, 12.0,
                              NULL);
      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.



                                    - 4 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



      XftFont *
      XftFontOpenName (Display       *dpy,
                       int           screen,
                       unsigned char *name);
      XftFontOpenName behaves as XftFontOpen does, except that it takes a
      Fontconfig pattern string (which is passed to the Fontconfig library's
      FcNameParse() function).

      XftFont *
      XftFontOpenXlfd (Display       *dpy,
                       int           screen,
                       unsigned char *xlfd)
      XftFontOpenXlfd behaves as XftFontOpen does, except that it takes a
      string containing an X Logical Font Description (XLFD).

      FcPattern *
      XftFontMatch (Display   *dpy,
                    int       screen,
                    FcPattern *pattern,
                    FcResult  *result);
      Also used internally by the XftFontOpen* functions, XftFontMatch can
      also be used directly to determine the Fontconfig font pattern
      resulting from an Xft font open request.  The FcPattern and FcResult
      data types are defined by the Fontconfig library.

    Determining the Pixel Extents of a Text String
      void
      XftTextExtents8 (Display    *dpy,
                       XftFont    *font,
                       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 characters when
      drawn with font, storing them in extents.  The FcChar8 data type is
      defined by the Fontconfig library, and the XGlyphInfo data type is
      defined by the X Rendering Extension library.

      void
      XftTextExtents16 (Display    *dpy,
                        XftFont    *font,
                        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 characters when
      drawn with font, storing them in extents.  The FcChar16 data type is
      defined by the Fontconfig library, and the XGlyphInfo data type is
      defined by the X Rendering Extension library.





                                    - 5 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



      void
      XftTextExtents32 (Display    *dpy,
                        XftFont    *font,
                        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.  The FcChar32 data type
      is defined by the Fontconfig library, and the XGlyphInfo data type is
      defined by the X Rendering Extension library.

      void
      XftTextExtentsUtf8 (Display    *dpy,
                          XftFont    *font,
                          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.  The XGlyphInfo data type is defined by the X
      Rendering Extension library.

      void
      XftTextExtentsUtf16 (Display    *dpy,
                           XftFont    *font,
                           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.  The FcEndian data type is defined by the
      Fontconfig library, and the XGlyphInfo data type is defined by the X
      Rendering Extension library.

      void
      XftGlyphExtents (Display    *dpy,
                       XftFont    *font,
                       FT_UInt    *glyphs,
                       int        nglyphs,
                       XGlyphInfo *extents);
      Also used internally by the XftTextExtents* functions, XftGlyphExtents
      computes the pixel extents on display dpy of no more than nglyphs in
      the array glyphs drawn with font, storing them in extents.  The
      FT_UInt data type is defined by the FreeType library, and the
      XGlyphInfo data type is defined by the X Rendering Extension library.

    Drawing Strings (and Other Things)
      XftDraw *



                                    - 6 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



      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.  The Drawable, Visual, and Colormap data types are defined by
      the X11 library.

      XftDraw *
      XftDrawCreateBitmap (Display *dpy,
                           Pixmap  bitmap);
      XftDrawCreateBitmap behaves as XftDrawCreate, except it uses an X
      pixmap of color depth 1 instead of an X drawable.  The Pixmap data
      type is defined by the X11 library.

      XftDraw *
      XftDrawCreateAlpha (Display *dpy,
                          Pixmap  pixmap,
                          int     depth);
      XftDrawCreateAlpha behaves as XftDrawCreate, except it uses an X
      pixmap of color depth depth instead of an X drawable.  The Pixmap data
      type is defined by the X11 library.

      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 associatied with the Xft draw
      object draw.

      Visual *
      XftDrawVisual (XftDraw *draw);
      XftDrawVisual returns a pointer to the visual associated with the Xft
      draw object draw.





                                    - 7 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



      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,
                         XftColor *color);
      This function is never called if the X server doesn't support the X
      Rendering Extension; instead, XftGlyphCore is used.

      void
      XftDrawDestroy (XftDraw *draw);
      XftDrawDestroy destroys draw (created by one of the XftCreate
      functions) and frees the memory that was allocated for it.

      void
      XftDrawString8 (XftDraw         *d,
                      XftColor        *color,
                      XftFont         *font,
                      int             x,
                      int             y,
                      unsigned char   *string,
                      int             len);
      XftDrawString8 draws no more than len glyphs of string to Xft drawable
      d using font in color at position x, y.

      void
      XftDrawRect (XftDraw        *d,
                   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.

 COMPATIBILITY
      As of version 2, Xft has become relatively stable and is expected to
      retain source and binary compatibility in future releases.

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

    Xft 1.x Compatibility Header File
      #include <X11/Xft/XftCompat.h>

    Xft 1.x Compatibility Data Types
      XftPattern
           holds a set of names with associated value lists; each name



                                    - 8 -       Formatted:  October 15, 2024






 Xft(__libmansuffix__)                                 Xft(__libmansuffix__)
                              __vendorversion__



           refers to a property of a font.  XftPatterns are used as inputs
           to the matching code as well as holding information about
           specific fonts.

      XftFontSet
           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.

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

 AUTHOR
      Keith Packard

 SEE ALSO
      Fontconfig Developers Reference
      FreeType API Reference
      Xlib - C Language Interface

































                                    - 9 -       Formatted:  October 15, 2024