Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Xft(3)									Xft(3)

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 program-
	      mers 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(), XftFontOpen-
	      Name(), XftFontOpenXlfd(), XftFontOpenInfo(), or XftFontOpenPat-
	      tern().	XftFontCopy()  is used to duplicate XftFonts, and Xft-
	      FontClose() 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 Render-
	      ing Extension Picture structures.	  Note:	 XftDrawGlyphs(),  the
	      XftDrawString*()	family,	 XftDrawCharSpec(),  and XftDrawGlyph-
	      Spec() 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.  Xft-
	      FontInfo 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  Xft-
	      FontOpenInfo().

       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(), Xft-
	      DrawGlyphs(), the	 XftDrawString*()  family,  XftDrawCharSpec(),
	      XftDrawCharFontSpec(),	 XftDrawGlyphSpec(),	 XftDrawGlyph-
	      FontSpec(), 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),  XftDrawCre-
	      ateBitmap(),  or	XftDrawCreateAlpha(),  and destroyed with Xft-
	      DrawDestroy().  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(), XftDrawCol-
	      ormap(),	and  XftDrawVisual(),  respectively.   The X Rendering
	      Extension	Picture	associated with	an XftDraw is returned by Xft-
	      DrawPicture().

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

	      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 automat-
       ically converted	to the correct pixel size based	on the	resolution  of
       the monitor.

       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 result-
       ing 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.

       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 Render-
       ing 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 *
       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  dis-
       play.  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.

       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	 func-
       tions) 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  ver-
       sion, 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
	      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.

       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 list-
	      ing fonts.

AUTHOR
       Keith Packard

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

X Version 11			 libXft	2.3.2				Xft(3)

NAME | DESCRIPTION | HEADER FILE | CONSTANTS | DATA TYPES | FUNCTIONS | COMPATIBILITY | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Xft&sektion=3&manpath=FreeBSD+11.0-RELEASE+and+Ports>

home | help