manpagez: man pages & more
man Xft(3)
Home | html | info | man
Xft(3)                            X Version 11                            Xft(3)




NAME

       Xft - X FreeType interface library


DESCRIPTION

       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.


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

       Xft datatypes follow a naming convention, prefixing all names with "Xft"

   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, Region,
       Visual, and XRectangle.

       Some datatypes are especially relevant to Xft:

       Drawable
            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 InputOnly
            window cannot be used as a source or destination in a graphics
            operation.

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

       Visual
            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:

              <X11/extensions/Xrender.h>

       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.

   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 programmers using
       Xft; it contains general font metrics and pointers to the Fontconfig
       character set and pattern associated with the font.

       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().

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

       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.

       Once 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().
       XftDraw objects 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 properties of an XftDraw
       can be queried with XftDrawDisplay(), XftDrawDrawable(),
       XftDrawColormap(), and XftDrawVisual(), respectively.

       Several functions use XftDraw objects: XftDrawCharFontSpec(),
       XftDrawCharSpec(), XftDrawGlyphFontSpec(), XftDrawGlyphSpec(),
       XftDrawGlyphs(), XftDrawRect(), XftDrawSetClip(),
       XftDrawSetClipRectangles(), XftDrawSetSubwindowMode(), and the
       XftDrawString*() family.

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

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

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

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

       XftCharFontSpec is used by XftCharFontSpecRender().

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

       XftGlyphSpec is used by XftDrawGlyphSpec().

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

       XftGlyphFontSpec is used by XftDrawGlyphFontSpec(), and
       XftGlyphFontSpecRender().


FUNCTIONS

   Initialization
       A typical application using Xft does not explicitly initialize the
       library.  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
       remainder 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 XRenderPictFormat
              (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:

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

                 XFT_MAX_UNREF_FONTS
                      (maxunreffonts).  This is the maximum number of
                      unreferenced fonts (default: 16).

                 XFT_TRACK_MEM_USAGE
                      (trackmemusage).  When true, Xft tracks usage of glyph
                      memory to improve performance when deciding which to
                      unload when the maximum amount of glyph memory is reached
                      (default: false).

              Xft also uses these default properties in XftDefaultSubstitute().


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

              Xft fills in missing properties in the given pattern using default
              properties for the specified display dpy, e.g., as set in
              XftDefaultSet().

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

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

                 FC_AUTOHINT
                      True if FreeType should use autohinting (default: False).

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

                 FC_EMBOLDEN
                      True if FT_GlyphSlot_Embolden() should be used to embolden
                      a font (default: False).

                 FC_HINTING
                      True if hinting should be used when filling in properties
                      to open a font (default: True).

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

                 FC_LCD_FILTER
                      Parameter passed to FT_Library_SetLcdFilter() when loading
                      glyphs (default: FC_LCD_DEFAULT).

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

                 FC_RGBA
                      RGBA value used when filling in properties to open a font
                      (default: computed by calling
                      XRenderQuerySubpixelOrder()).

                 FC_SCALE
                      Scale used in Fontconfig (default: 1.0).

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

                 XFT_RENDER
                      True if the display supports X Render extension (default:
                      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 done.


       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 actual
              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 pattern
              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.

       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.

       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 Fontconfig
              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 pattern
              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
              average_width.

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

                 FC_FOUNDRY
                      from foundry.

                 FC_FAMILY
                      from family.

                 FC_WEIGHT
                      weight_name, defaulting to FC_WEIGHT_MEDIUM.

                 FC_SLANT
                      from slant, defaulting to FC_SLANT_ROMAN.

                 FC_SIZE
                      from point_size.

                 FC_PIXEL_SIZE
                      from pixel_size.  If point_size was set, as well as
                      resolution_xand resolution_y, then the value is scaled
                      convert 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
              characters 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
              characters 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,
              XftGlyphExtents 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()
                  returns False, and does not update the XftColor referenced by
                  result.

              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
                  returns 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(), XftDrawGlyphSpec(),
              XftDrawGlyphFontSpec(), respectively.

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


       void XftDrawDestroy (
                      XftDraw               *draw);

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


       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
                  Region (to copy the parameter),

              o   Xft destroys any existing clipping region.

              o   Xft sets the clip_type for the draw parameter to
                  XftClipTypeRegion 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 clipping
              for the given XftDraw parameter draw but uses a set of n
              rectangles (the rects parameter) which could be used to construct
              a Region .

              Xft sets the clip_type for draw to XftClipTypeRectangles and uses
              XSetClipRectangles() for core (X11) clipping and
              XRenderSetPictureClipRectangles() 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
              IncludeInferiors:

              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 subwindow
                  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
              XRenderChangePicture().

   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
              XftGlyphFontSpecRender() 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
              coordinates, 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
                  XftFontLoadGlyphs().

              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
                  remembers which was the first font used, and computes the
                  position 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 extension
                  to draw the glyphs, with the appropriate
                  XRenderCompositeText*() function according to the width, and
                  discards temporary data.

                  The op, dst, src, srcx, and srcy parameters are used as
                  described 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
              FcPatternDestroy().


       FcPattern *XftNameParse (
                      _Xconst char          *name);

              Xft uses Fontconfig to parse the name, passing the name to
              FcNameParse(), 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 (Unicode
              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 bounding
              box, clip the glyphs into those bounds, scale the glyphs, compute
              font metrics, and add it to the X Render extension using
              XRenderAddGlyphs().


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

              Discards data for up to nglyph glyphs whose glyph indices (Unicode
              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 associated 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
              XftFontLoadGlyphs(), 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
              provided for hiding private symbols.


       void XftUnlockFace (
                      XftFont               *pub);

              Decrements the reference count for the FreeType 2 "face"
              associated 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().


DEBUGGING

       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

       1024 shows details on extended management of glyph cached-memory


COMPATIBILITY

       As of version 2 (May 2002), Xft became relatively stable.  It is expected
       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
       XftPattern
              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 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
       Thomas E. Dickey (performance improvements)


SEE ALSO

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



X Version 11                      libXft 2.3.6                            Xft(3)

Xft2 2.3.6 - Generated Tue Sep 20 11:10:58 CDT 2022
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.