path: root/man/Xft.man

.\"
.\" Copyright © 2022 Thomas E. Dickey
.\" Copyright © 2000 Keith Packard
.\"
.\" Permission to use, copy, modify, distribute, and sell this software and its
.\" documentation for any purpose is hereby granted without fee, provided that
.\" the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation, and that the name of the above copyright holders not be used
.\" in advertising or publicity pertaining to distribution of the software
.\" without specific, written prior permission.  The above copyright holders
.\" make no representations about the suitability of this software for any
.\" purpose.  It is provided "as is" without express or implied warranty.
.\"
.\" THE ABOVE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
.\" SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL,
.\" INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.de TA
.ie n  .ta 0.8i 1.6i 2.4i 3.2i
.el    .ta 0.5i 1.0i 1.5i 2.0i
..
.de PS
.sp
.ns
.TP \\$1
.na
.nf
.ie n  .ta 0.8i 3.0i
.el    .ta 0.5i 2.0i
..
.de PE
.br
.ad
.fi
.sp
.TA
..
.de QS
.in +.2i
.nf
.na
.ie n  .ta 1.0i 3.0i
.el    .ta 0.6i 2.0i
..
.de QC
.QS
.ie n  .ta 2.0i 3.0i
.el    .ta 1.6i 2.6i
.ft CR
..
.de QE
.in -.2i
.ft
.fi
.ad
.TA
..
.de bP
.ie n  .IP \(bu 4
.el    .IP \(bu 2
..
.ie \n(.g .ds `` \(lq
.el       .ds `` ``
.ie \n(.g .ds '' \(rq
.el       .ds '' ''
.TH Xft __libmansuffix__ __vendorversion__ "X Version 11"
.SH NAME
Xft \- X FreeType interface library
.SH DESCRIPTION
.B Xft
is a simple library which draws text and graphics:
.bP
using information provided by the Fontconfig library,
.bP
.B Xft
converts font glyphs using the FreeType rasterizer, and
.bP
displays the converted font data using the X Rendering Extension.
.PP
This manual page barely scratches the surface of this library.
.SH "HEADER FILE"
.B #include <X11/Xft/Xft.h>
.SH CONSTANTS
.TP
.B XFT_MAJOR
is the major version number of
.BR Xft .
.TP
.B XFT_MINOR
is the minor version number of
.BR Xft .
.TP
.B XFT_REVISION
is the revision number of
.BR Xft .
.TP
.B XFT_VERSION
is
.B XFT_MAJOR
times 10000 (ten thousand), plus
.B XFT_MINOR
times 100, plus
.BR XFT_REVISION .
.TP
.B XftVersion
is an alias for
.BR XFT_VERSION .
.PP
The following example illustrates how
.BR Xft 's
version constants might be used:
.QS
    #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.\(rsn", XFT_MAJOR,
                  XFT_MINOR,
                  XFT_REVISION);
    #endif
.QE
.\" I don't understand what these are for.  -- BR, 2005-04-02
.\" XFT_XLFD                used in xftname.c, xftxlfd.c
.\" XFT_NMISSING            used in xftcore.c, xftextent.c, xftglyphs.c,
.\"                                 xftrender.c
.SH "DATA TYPES"
.SS XftFont
.QS
typedef struct _XftFont {
	int	 ascent;
	int	 descent;
	int	 height;
	int	 max_advance_width;
	FcCharSet	*charset;
	FcPattern	*pattern;
} XftFont;
.QE
.PP
An
.B XftFont
is the primary data structure of interest to programmers using
.BR Xft ;
it contains general font metrics and pointers to the Fontconfig
character set and pattern associated with the font.
The
.B FcCharSet
and
.B FcPattern
data types are defined by the Fontconfig library.
.PP
.BR XftFont s
are populated with any of
.BR XftFontOpen (),
.BR XftFontOpenName (),
.BR XftFontOpenXlfd (),
.BR XftFontOpenInfo (),
or
.BR XftFontOpenPattern ().
.BR XftFontCopy ()
is used to duplicate
.BR XftFont s,
and
.BR XftFontClose ()
is used to mark an
.B XftFont
as unused.
.BR XftFont s
are internally allocated, reference-counted, and freed by
.BR Xft ;
the programmer does not ordinarily need to allocate or free storage
for them.
.PP
.BR XftDrawGlyphs (),
the
.BR XftDrawString *()
family,
.BR XftDrawCharSpec (),
and
.BR XftDrawGlyphSpec ()
use
.BR XftFont s
to render text to an
.B XftDraw
object, which may correspond to either a core X drawable or an X
Rendering Extension drawable.
.PP
.BR XftGlyphExtents ()
and the
.BR XftTextExtents *()
family are used to determine the extents (maximum dimensions) of an
.BR XftFont .
.PP
An
.BR XftFont 's
glyph or character coverage can be determined with
.BR XftFontCheckGlyph ()
or
.BR XftCharExists ().
.BR XftCharIndex ()
returns the
.BR XftFont -specific
character index corresponding to a given Unicode codepoint.
.PP
.BR XftGlyphRender (),
.BR XftGlyphSpecRender (),
.BR XftCharSpecRender (),
and the
.BR XftTextRender *()
family use
.BR XftFont s
to draw into X Rendering Extension
.B Picture
structures.
.PP
.B Note:
.BR XftDrawGlyphs (),
the
.BR XftDrawString *()
family,
.BR XftDrawCharSpec (),
and
.BR XftDrawGlyphSpec ()
provide a means of rendering fonts that is independent of the
availability of the X Rendering Extension on the X server.
.SS
.B XftFontInfo
is an opaque object that stores information about a font.
.B XftFontInfo
structures are created with
.BR XftFontInfoCreate (),
freed with
.BR XftFontInfoDestroy (),
and compared with
.BR XftFontInfoEqual ().
.B XftFontInfo
objects are internally allocated and freed by
.BR Xft ;
the programmer does not ordinarily need to allocate or free storage
for them.
.PP
Each
.B XftFontInfo
structure in use is associated with a unique identifier, which can be
retrieved with
.BR XftFontInfoHash ().
An
.B XftFont
can be opened based on
.B XftFontInfo
data with
.BR XftFontOpenInfo ().
.SS
.B XftColor
.QS
typedef struct _XftColor {
	unsigned long	 pixel;
	XRenderColor	 color;
} XftColor;
.QE
.PP
An
.B 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
.B XRenderColor
data type is defined by the X Render Extension library.
.PP
.BR XftColorAllocName ()
and
.BR XftColorAllocValue ()
request a color allocation from the X server (if necessary) and
initialize the members of
.BR XftColor .
.BR XftColorFree ()
instructs the X server to free the color currently allocated for an
.BR XftColor .
.PP
Once an
.B XftColor
has been initialized,
.BR XftDrawSrcPicture (),
.BR XftDrawGlyphs (),
the
.BR XftDrawString *()
family,
.BR XftDrawCharSpec (),
.BR XftDrawCharFontSpec (),
.BR XftDrawGlyphSpec (),
.BR XftDrawGlyphFontSpec (),
and
.BR XftDrawRect ()
may be used to draw various objects using it.
.SS
.B 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.
.PP
.B XftDraw
objects are created with any of
.BR XftDrawCreate ()
(which associates an
.B XftDraw
with an existing X drawable),
.BR XftDrawCreateBitmap (),
or
.BR XftDrawCreateAlpha (),
and destroyed with
.BR XftDrawDestroy ().
The X drawable associated with an
.B XftDraw
can be changed with
.BR XftDrawChange ().
.B XftDraw
objects are internally allocated and freed by
.BR Xft ;
the programmer does not ordinarily need to allocate or free storage
for them.
.PP
The X
.BR Display ,
.BR Drawable ,
.BR Colormap ,
and
.B Visual
properties of an
.B XftDraw
can be queried with
.BR XftDrawDisplay (),
.BR XftDrawDrawable (),
.BR XftDrawColormap (),
and
.BR XftDrawVisual (),
respectively.
.PP
Several functions use
.B XftDraw
objects:
.BR XftDrawCharFontSpec (),
.BR XftDrawCharSpec (),
.BR XftDrawGlyphFontSpec (),
.BR XftDrawGlyphSpec (),
.BR XftDrawGlyphs (),
.BR XftDrawRect (),
.BR XftDrawSetClip (),
.BR XftDrawSetClipRectangles (),
.BR XftDrawSetSubwindowMode (),
and the
.BR XftDrawString *()
family.
.PP
The X Rendering Extension
.B Picture
associated with an
.B XftDraw
is returned by
.BR XftDrawPicture (),
and
.BR XftDrawSrcPicture ().
It is used by
.BR XftCharFontSpecRender (),
.BR XftCharSpecRender (),
.BR XftGlyphFontSpecRender (),
.BR XftGlyphRender (),
.BR XftGlyphSpecRender (),
and the
.BR XftTextRender *()
family.
.SS
.B XftCharSpec
.QS
typedef struct _XftCharSpec {
	FcChar32	 ucs4;
	short	 x;
	short	 y;
} XftCharSpec;
.QE
.PP
The
.B FcChar32
data type is defined by the Fontconfig library.
.B XftCharSpec
is used by
.BR XftDrawCharSpec (),
and
.BR XftCharSpecRender ().
.SS
.B XftCharFontSpec
.QS
typedef struct _XftCharFontSpec {
	XftFont	*font;
	FcChar32	 ucs4;
	short	 x;
	short	 y;
} XftCharFontSpec;
.QE
.PP
The
.B FcChar32
data type is defined by the Fontconfig library.
.SS
.B XftGlyphSpec
.QS
typedef struct _XftGlyphSpec {
	FT_UInt	  glyph;
	short	  x;
	short	  y;
} XftGlyphSpec;
.QE
.PP
The
.B FT_UInt
data type is defined by the FreeType library.
.SS XftGlyphFontSpec
.QS
typedef struct _XftGlyphFontSpec {
	XftFont	*font;
	FT_UInt	 glyph;
	short	 x;
	short	 y;
} XftGlyphFontSpec;
.QE
.PP
The
.B FT_UInt
data type is defined by the FreeType library.
.SH FUNCTIONS
.\" *************************************************************************
.SS "Initialization"
A typical application using
.B Xft
does not explicitly initialize the library.
That is usually done as a side-effect of opening a font.
.PP
When
.B 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.
.PP
Not all of the collected information is stored in a pattern.
The remainder is stored in internal data structures.
.B Xft
makes some of that available to the application via functions.
.PS
\fBBool\fP \fBXftDefaultHasRender\fP (
	\fBDisplay\fP	*\fIdpy\fP);
.PE
Obtain information about the display
.I dpy
if not done already, and
return true if
.B Xft
found that the display supports the X Render extension,
and if it is able to find a suitable
.B XRenderPictFormat 
(X Render's datatype which is analogous to Xlib's Visual)
on the display.
.PS
\fBBool\fP \fBXftDefaultSet\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBFcPattern\fP	*\fIdefaults\fP);
.PE
Obtain information about the display
.I dpy
if not done already, and
set the Fontconfig pattern holding default properties
which
.B Xft
will use for this display.
.IP
.B Xft
uses those properties initially to obtain these limits:
.RS 10
.TP 5
XFT_MAX_GLYPH_MEMORY
(maxglyphmemory).
This is the maximum amount of glyph memory for all fonts used by
.B Xft
(default: 4*1024*1024).
.TP 5
XFT_MAX_UNREF_FONTS
(maxunreffonts).
This is the maximum number of unreferenced fonts
(default: 16).
.RE
.IP
.B Xft
also uses these default properties in
.BR XftDefaultSubstitute ().
.PS
\fBvoid\fP \fBXftDefaultSubstitute\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBint\fP	 \fIscreen\fP,
	\fBFcPattern\fP	*\fIpattern\fP);
.PE
.B Xft
fills in missing properties in the given
.I pattern
using default properties for the specified display
.IR dpy ,
e.g., as set in
.BR XftDefaultSet ().
.IP
Typical
.B Xft
applications use this function to help Fontconfig
choose a suitable font.
These properties are substituted before calling
.BR FcDefaultSubstitute ():
.RS 10
.TP 5
FC_ANTIALIAS
True if FreeType should use antialiasing
(default: False).
(default: True).
.TP 5
FC_AUTOHINT
True if FreeType should use autohinting
(default: False).
.TP 5
FC_DPI
Dots/inch used for resolution
(default: computed from the display height).
.TP 5
FC_EMBOLDEN
True if
.BR FT_GlyphSlot_Embolden ()
should be used to embolden a font
(default: False).
.TP 5
FC_HINTING
True if hinting should be used when filling in properties to open a font
(default: True).
.TP 5
FC_HINT_STYLE
Hinting style used when filling in properties to open a font
(default: FC_HINT_FULL).
.TP 5
FC_LCD_FILTER
Parameter passed to
.BR FT_Library_SetLcdFilter ()
when loading glyphs
(default: FC_LCD_DEFAULT).
.TP 5
FC_MINSPACE
Minimum space value used when filling in properties to open a font
(default: False).
.TP 5
FC_RGBA
RGBA value used when filling in properties to open a font
(default: computed by calling
.BR XRenderQuerySubpixelOrder ()).
.TP 5
FC_SCALE
Scale used in Fontconfig
(default: 1.0).
.TP 5
XFT_MAX_GLYPH_MEMORY
Maximum memory for one font
(default: 1024*1024).
.TP 5
XFT_RENDER
True if the display supports X Render extension
(default: result from
.BR XftDefaultHasRender ()).
.RE
.PS
\fBFcBool\fP \fBXftInit\fP (
	\fB_Xconst char\fP	*\fIconfig\fP);
.PE
Initializes the Fontconfig library (calling
.BR FcInit ()).
.IP
The \fIconfig\fP parameter is unused.
.IP
.B Xft
does not deinitialize the Fontconfig library when it is done.
.PS
\fBFcBool\fP \fBXftInitFtLibrary\fP (\fBvoid\fP);
.PE
Initializes the FreeType library
(calling
.BR 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.
.IP
.B Xft
calls
.BR XftInitFtLibrary ()
internally via
.BR XftFontInfoCreate "() and"
.BR XftFontOpenPattern ().
.IP
.B Xft
does not discard the library object
(e.g., using
.BR FT_Done_FreeType ())
when it is done.
.PS
\fBint\fP \fBXftGetVersion\fP (\fBvoid\fP);
.PE
Returns \fBXftVersion\fP, enabling an application to determine the
actual version of
.B Xft
which is in use.
.\" *************************************************************************
.SS "Opening and Matching Fonts"
.PS
\fBXftFont\fP *\fBXftFontOpen\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBint\fP	 \fIscreen\fP,
	...);
.PE
.B XftFontOpen
takes a list of pattern element triples of the form
.IR 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
.I screen
on display
.IR dpy .
The
.B Display
data type is defined by the X11 library.
Returns NULL if no match is found.
.PP
Example:
.QS
    font = XftFontOpen (dpy, screen,
                        XFT_FAMILY, XftTypeString, "charter",
                        XFT_SIZE, XftTypeDouble, 12.0,
                        NULL);
.QE
.IP
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.
.PP
.PS
\fBXftFont\fP *\fBXftFontOpenName\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBint\fP	 \fIscreen\fP,
	\fB_Xconst char\fP	*\fIname\fP);
.PE
.B XftFontOpenName
behaves as
.B XftFontOpen
does, except that it takes a Fontconfig pattern string (which is passed to
the Fontconfig library's
.BR FcNameParse ()
function).
.PP
.PS
\fBXftFont\fP *\fBXftFontOpenXlfd\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBint\fP	 \fIscreen\fP,
	\fB_Xconst char\fP	*\fIxlfd\fP)
.PE
.B XftFontOpenXlfd
behaves as
.B XftFontOpen
does, except that it takes a string containing an X Logical Font
Description (XLFD),
and uses the
.BR XftXlfdParse ()
function.
.PP
.PS
\fBFcPattern\fP *\fBXftFontMatch\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBint\fP	 \fIscreen\fP,
	\fB_Xconst FcPattern\fP	*\fIpattern\fP,
	\fBFcResult\fP	*\fIresult\fP);
.PE
Also used internally by the
.BR XftFontOpen *
functions,
.B XftFontMatch
can also be used directly to determine the Fontconfig font pattern
resulting from an
.B Xft
font open request.
The
.B FcPattern
and
.B FcResult
data types are defined by the Fontconfig library.
.PS
\fBFcPattern\fP *\fBXftXlfdParse\fP (
	\fB_Xconst char\fP	*\fIxlfd_orig\fP,
	\fBBool\fP	\fIignore_scalable\fP,
	\fBBool\fP	\fIcomplete\fP);
.PE
.B XftXlfdParse
parses the
.I xlfd_orig
parameter according to the
.I X Logical Font Description Conventions
document, but ignores
some of the fields:
.IR setwidth_name ,
.IR add_style_name  ,
.IR spacing  ,
and
.IR average_width .
.IP
.B XftXlfdParse
creates a Fontconfig pattern,
setting
.I XFT_XLFD
to the
.I xlfd_orig
value,
and
maps the collected information to Fontconfig properties.
Empty or \*(``*\*('' fields are ignored:
.RS 10
.TP 5
FC_FOUNDRY
from
.IR foundry .
.TP 5
FC_FAMILY
from
.IR family .
.TP 5
FC_WEIGHT
.IR weight_name ,
defaulting to
FC_WEIGHT_MEDIUM.
.TP 5
FC_SLANT
from
.IR slant ,
defaulting to
FC_SLANT_ROMAN.
.TP 5
FC_SIZE
from
.IR point_size .
.TP 5
FC_PIXEL_SIZE
from 
.IR pixel_size .
If
.I point_size
was set, as well as
.IR resolution_x and
.IR resolution_y ,
then the value is scaled convert the font's height to points.
.RE
.\" *************************************************************************
.SS "Determining Text Extents"
.B Xft
provides several functions for determining the required height and width
for displaying a text-string.
After accounting for the
.IR offset ,
in cases where the string will be shifted up, down, left or right,
these numbers are referred to as
.IR "text extents" .
.PS
\fBvoid\fP \fBXftTextExtents8\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fB_Xconst FcChar8\fP	*\fIstring\fP,
	\fBint\fP	 \fIlen\fP,
	\fBXGlyphInfo\fP	*\fIextents\fP);
.PE
.B XftTextExtents8
computes the pixel extents on display
.I dpy
of no more than
.I len
glyphs of a
.I string
consisting of eight-bit characters when drawn with
.IR font ,
storing them in
.IR extents .
The
.B FcChar8
data type is defined by the Fontconfig library, and the
.B XGlyphInfo
data type is defined by the X Rendering Extension library.
.PP
.PS
\fBvoid\fP \fBXftTextExtents16\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fB_Xconst FcChar16\fP	*\fIstring\fP,
	\fBint\fP	 \fIlen\fP,
	\fBXGlyphInfo\fP	*\fIextents\fP);
.PE
.B XftTextExtents16
computes the pixel extents on display
.I dpy
of no more than
.I len
glyphs of a
.I string
consisting of sixteen-bit characters when drawn with
.IR font ,
storing them in
.IR extents .
The
.B FcChar16
data type is defined by the Fontconfig library, and the
.B XGlyphInfo
data type is defined by the X Rendering Extension library.
.PP
.PS
\fBvoid\fP \fBXftTextExtents32\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fB_Xconst FcChar32\fP	*\fIstring\fP,
	\fBint\fP	 \fIlen\fP,
	\fBXGlyphInfo\fP	*\fIextents\fP);
.PE
.B XftTextExtents32
computes the pixel extents on display
.I dpy
of no more than
.I len
glyphs of a
.I string
consisting of thirty-two-bit characters when drawn with
.IR font ,
storing them in
.IR extents .
The
.B FcChar32
data type is defined by the Fontconfig library, and the
.B XGlyphInfo
data type is defined by the X Rendering Extension library.
.PP
.PS
\fBvoid\fP \fBXftTextExtentsUtf8\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fB_Xconst FcChar8\fP	*\fIstring\fP,
	\fBint\fP	 \fIlen\fP,
	\fBXGlyphInfo\fP	*\fIextents\fP);
.PE
.B XftTextExtentsUtf8
computes the pixel extents on display
.I dpy
of no more than
.I len
bytes of a UTF-8 encoded
.I string
when drawn with
.IR font ,
storing them in
.IR extents .
The
.B XGlyphInfo
data type is defined by the X Rendering Extension library.
.PP
.PS
\fBvoid\fR \fBXftTextExtentsUtf16\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fB_Xconst FcChar8\fP	*\fIstring\fP,
	\fBFcEndian\fP	 \fIendian\fP,
	\fBint\fP	 \fIlen\fP,
	\fBXGlyphInfo\fP	*\fIextents\fP);
.PE
.B XftTextExtentsUtf16
computes the pixel extents on display
.I dpy
of no more than
.I len
bytes of a UTF-16LE- or UTF-16BE-encoded
.I string
when drawn with
.IR font ,
storing them in
.IR extents .
The endianness of
.I string
must be specified in
.IR endian .
The
.B FcEndian
data type is defined by the Fontconfig library, and the
.B XGlyphInfo
data type is defined by the X Rendering Extension library.
.PP
.PS
\fBvoid\fP \fBXftGlyphExtents\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fB_Xconst FT_UInt\fP	*\fIglyphs\fP,
	\fBint\fP	 \fInglyphs\fP,
	\fBXGlyphInfo\fP	*\fIextents\fP);
.PE
Also used internally by the
.BR XftTextExtents *()
functions,
.B XftGlyphExtents
computes the pixel extents on display
.I dpy
of no more than
.I nglyphs
in the array
.I glyphs
drawn with
.IR font ,
storing them in
.IR extents .
The
.B FT_UInt
data type is defined by the FreeType library, and the
.B XGlyphInfo
data type is defined by the X Rendering Extension library.
.IP
If any of the
.I glyphs
are missing (determined by a check with
.BR XftFontCheckGlyph ()),
the corresponding entry in
.I extents
is filled with zeroes.
.\" *************************************************************************
.SS "Drawing Strings (and Other Things)"
.PS
\fBXftDraw\fP *\fBXftDrawCreate\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBDrawable\fP	 \fIdrawable\fP,
	\fBVisual\fP	*\fIvisual\fP,
	\fBColormap\fP	 \fIcolormap\fP);
.PE
.B XftDrawCreate
creates a structure that can be used to render text and rectangles using
the specified
.IR drawable ,
.IR visual ,
and
.I colormap
on
.IR display .
The
.BR Drawable ,
.BR Visual ,
and
.B Colormap
data types are defined by the X11 library.
.PP
.PS
\fBXftDraw\fP *\fBXftDrawCreateBitmap\fP (
	\fBDisplay\fP	*\fIdpy\fB,\fR
	\fBPixmap\fP	 \fIbitmap\fB);\fR
.PE
.B XftDrawCreateBitmap
behaves as
.BR XftDrawCreate (),
except it uses an X pixmap of color depth 1 instead of an X drawable.
The
.B Pixmap
data type is defined by the X11 library.
.PP
.PS
\fBXftDraw *\fP \fBXftDrawCreateAlpha\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBPixmap\fP	 \fIpixmap\fP,
	\fBint\fP	 \fIdepth\fP);
.PE
.B XftDrawCreateAlpha
behaves as
.BR XftDrawCreate (),
except it uses an X pixmap of color depth
.I depth
instead of an X drawable.
The
.B Pixmap
data type is defined by the X11 library.
.PP
.PS
\fBvoid\fP \fBXftDrawChange\fP (
	\fBXftDraw\fP	*\fIdraw\fP,
	\fBDrawable\fP	 \fIdrawable\fP);
.PE
.B XftDrawChange
changes the X drawable association of the existing
.B Xft
draw object
.I draw
from its current value to
.IR drawable .
.PP
.PS
\fBDisplay\fP *\fBXftDrawDisplay\fP (
	\fBXftDraw\fP	*\fIdraw\fP);
.PE
.B XftDrawDisplay
returns a pointer to the display associated with the
.B Xft
draw object
.IR draw .
.PP
.PS
\fBDrawable\fP \fBXftDrawDrawable\fP (
	\fBXftDraw\fP	*\fIdraw\fP);
.PE
.B XftDrawDrawable
returns the X drawable associated with the
.B Xft
draw object
.IR draw .
.PP
.PS
\fBColormap\fP \fBXftDrawColormap\fP (
	\fBXftDraw\fP	*\fIdraw\fP);
.PE
.BR XftDrawColormap ()
returns the colormap associated with the
.B Xft
draw object
.IR draw .
.PP
.PS
\fBVisual\fR *\fBXftDrawVisual\fP (
	\fBXftDraw\fP	*\fIdraw\fP);
.PE
.B XftDrawVisual
returns a pointer to the visual associated with the
.B Xft
draw object
.IR draw .
.PP
.PS
\fBPicture\fP \fBXftDrawPicture\fP (
	\fBXftDraw\fP	*\fIdraw\fP);
.PE
.B XftDrawPicture
returns the picture associated with the
.B Xft
draw object
.IR draw .
If the the X server does not support the X Rendering Extension, 0 is
returned.
.PP
.PS
\fBPicture\fP \fBXftDrawSrcPicture\fP (
	\fBXftDraw\fP	*\fIdraw\fP,
	\fB_Xconst XftColor\fP	*\fIcolor\fP);
.PE
.\" Unfortunately, I'm not quite sure what this does.  I think it is the gizmo
.\" that is used to create an Xrender Picture object so that glyphs can be
.\" drawn in the XftDraw object
.\" .I draw
.\" using the specified
.\" .IR color .
.\" -- BR, 2005-04-02
This function is never called if the X server doesn't support the X
Rendering Extension; instead,
.B XftGlyphCore
is used.
.PP
.PS
\fBvoid\fP \fBXftDrawDestroy\fP (
	\fBXftDraw\fP	*\fIdraw\fP);
.PE
.B XftDrawDestroy
destroys
.I draw
(created by one of the
.B XftCreate
functions) and frees the memory that was allocated for it.
.PP
.PS
\fBvoid\fP \fBXftDrawString8\fP (
	\fBXftDraw\fP	*\fId\fP,
	\fB_Xconst XftColor\fP	*\fIcolor\fP,
	\fBXftFont\fP	*\fIfont\fP,
	\fBint\fP	 \fIx\fP,
	\fBint\fP	 \fIy\fP,
	\fB_Xconst FcChar8\fP	*\fIstring\fP,
	\fBint\fP	 \fIlen\fP);
.PE
.B XftDrawString8
draws no more than
.I len
glyphs of
.I string
to
.B Xft
drawable
.I d
using
.I font
in
.I color
at position
.IR x , " y" .
.PP
.PS
\fBvoid\fP \fBXftDrawRect\fP (
	\fBXftDraw\fP	*\fId\fP,
	\fB_Xconst XftColor\fP	*\fIcolor\fP,
	\fBint\fP	 \fIx\fP,
	\fBint\fP	 \fIy\fP,
	\fBunsigned int\fP	 \fIwidth\fP,
	\fBunsigned int\fP	 \fIheight\fP);
.PE
.B XftDrawRect
draws a solid rectangle of the specified
.IR color ,
.IR width ,
and
.I height
at position
.IR x , " y"
to
.B Xft
drawable
.IR d .
.SS Manipulating patterns
.PS
\fBFcFontSet\fP *\fBXftListFonts\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBint\fP	 \fIscreen\fP,
	...);
.PE
.B Xft
uses
.BR FcPatternVapBuild ()
and
.BR FcObjectSetVapBuild ()
to process the variable-length parameter list,
and
.BR FcFontList ()
to obtain a list of matching Fontconfig patterns,
which it returns to the caller.
The caller can dispose of the return value using
.BR FcPatternDestroy ().
.PS
\fBFcPattern\fP *\fBXftNameParse\fP (
	\fB_Xconst char\fP	*\fIname\fP);
.PE
.B Xft
uses Fontconfig to parse the name,
passing the
.I name
to
.BR FcNameParse (),
returning the result.
.PS
\fBFcBool\fP \fBXftNameUnparse\fP (
	\fBFcPattern\fP	*\fIpat\fP,
	\fBchar\fP	*\fIdest\fP,
	\fBint\fP	 \fIlen\fP);
.PE
Like
.BR XfgNameParse (),
.B Xft
uses Fontconfig.
In this case, it uses
.BR FcNameUnparse (),
which converts the pattern
.I pat
back into a string that can be parsed.
.BR XftNameUnparse ()
stores the result via the caller's pointer
.IR dest ,
but checks first if it will fit,
using the
.I len
parameter.
If it fits,
.B Xft
copies the string and returns
.BR FcTrue ,
otherwise it returns
.BR FcFalse .
.SS Manipulating Font data
.PS
\fBvoid\fP \fBXftFontLoadGlyphs\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIpub\fP,
	\fBFcBool\fP	 \fIneed_bitmaps\fP,
	\fB_Xconst FT_UInt\fP	*\fIglyphs\fP,
	\fBint\fP	 \fInglyph\fP);
.PE
Using
.BR FT_Load_Glyph (),
load
.I nglyphs 
for the glyph indices (Unicode values)
listed in the array
.I glyphs
from the given font
.IR pub .
.IP
Loading a glyph entails more than just reading data into memory.
.B Xft
uses the Fontconfig pattern associated with the display
.I dpy 
(e.g., via
.BR 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
.BR XRenderAddGlyphs ().
.PS
\fBvoid\fP \fBXftFontUnloadGlyphs\fP (
	\fBDisplay\fP	*\fIdpy\fP,
	\fBXftFont\fP	*\fIpub\fP,
	\fB_Xconst FT_UInt\fP	*\fIglyphs\fP,
	\fBint\fP	 \fInglyph\fP);
.PE
Discards data for up to
.I nglyph
glyphs whose glyph indices (Unicode values)
are listed in the array
.I glyphs
for the given font
.IR pub .
If the glyphs were added to the X Render extension,
.B Xft
removes those using
.BR XRenderFreeGlyphs ().
.B Xft
keeps track of the amount of memory used for glyphs,
and updates the usage associated with the display
.IR dpy .
.PS
\fBFT_Face\fP \fBXftLockFace\fP (
	\fBXftFont\fP	*\fIpub\fP);
.PE
If no FreeType 2 \*(``face\*(''
(in-memory representation of a given typeface in a given style)
has been created for the
.I pub
font, create one using
.BR FT_New_Face ().
Face-locks are a reference count used by
.B Xft
to ensure that only one face is created,
and that it is retained until the font is no longer used.
.IP
Face-locking is used directly in
.BR XftCharIndex ()
and
.BR XftFontLoadGlyphs (),
which in turn are used in many functions of
.BR Xft .
.IP
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.
.PS
\fBvoid\fP \fBXftUnlockFace\fP (
	\fBXftFont\fP	*\fIpub\fP);
.PE
Decrements the reference count for the FreeType 2 \*(``face\*(''
associated with the font.
.IP
.B FT_Face
objects are deallocated using
.BR FT_Done_Face ().
.B Xft
does this in
.BR XftFontInfoDestroy ()
and when cleaning up on failure in 
.BR XftFontInfoCreate ()
and
.BR XftFontOpenPattern ().
.SH COMPATIBILITY
As of version 2 (May 2002),
.B Xft
became relatively stable.
It is expected to retain source and binary compatibility in future releases.
.PP
.B Xft
provides a compatibility interface to its previous major version,
Xft
.RI 1. x ,
described below.
.\" *************************************************************************
.SS "Xft 1.x Compatibility Header File"
.B #include <X11/Xft/XftCompat.h>
.\" .SS "Xft 1.x Compatibility Constants"
.SS "Xft 1.x Compatibility Data Types"
.TP
.B XftPattern
holds a set of names with associated value lists; each name refers to a
property of a font.
.BR XftPattern s
are used as inputs to the matching code as well as holding information
about specific fonts.
.TP
.B XftFontSet
contains a list of
.BR XftPattern s.
Internally,
.B Xft
uses this data structure to hold sets of fonts.
Externally,
.B Xft
returns the results of listing fonts in this format.
.TP
.B 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.
.\" .SS "Xft 1.x Compatibility Functions"
.SH AUTHOR
Keith Packard
.SH "SEE ALSO"
.I Fontconfig Developers Reference
.br
.I FreeType API Reference
.br
.I Xlib \- C Language Interface
.br
.I X Logical Font Description Conventions
.\" Set Vim modeline; textwidth is 70 to account for the extra margin
.\" padding that man (on Debian GNU/Linux) does for output to
.\" terminals (7 spaces on the left, 2 on the right), so that we don't
.\" go past 80 columns total, particularly in .nf/.fi regions.
.\" vim:set ai et sts=4 sw=4 tw=70: