initial draft of initialization-functions documentation

Signed-off-by: Thomas E. Dickey <dickey@invisible-island.net>

1 files changed, 186 insertions, 16 deletions

diff --git a/man/Xft.man b/man/Xft.man
index a23e984..6ae98d5 100644
--- a/man/Xft.man
+++ b/man/Xft.man
@@ -1,22 +1,23 @@
 .\"
+.\" 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 Keith Packard not be used in
-.\" advertising or publicity pertaining to distribution of the software without
-.\" specific, written prior permission.  Keith Packard makes no
-.\" representations about the suitability of this software for any purpose.  It
-.\" is provided "as is" without express or implied warranty.
+.\" 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.
 .\"
-.\" KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
-.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
-.\" EVENT SHALL KEITH PACKARD 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
+.\" 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
@@ -72,8 +73,14 @@
 Xft \- X FreeType interface library
 .SH DESCRIPTION
 .B Xft
-is a simple library designed to interface the FreeType rasterizer with the X
-Rendering Extension.
+is a simple library which draws text and graphics:
+.bP
+using information provided by the Fontconfig library,
+.bP
+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>
@@ -119,10 +126,7 @@ version constants might be used:
 .QE
 .\" I don't understand what these are for.  -- BR, 2005-04-02
 .\" XFT_CORE                used in xftname.c
-.\" XFT_RENDER              used in xftdpy.c, xftfreetype.c, xftname.c
 .\" XFT_XLFD                used in xftname.c, xftxlfd.c
-.\" XFT_MAX_GLYPH_MEMORY    used in xftdpy.c, xftfreetype.c
-.\" XFT_MAX_UNREF_FONTS     used in xftdpy.c
 .\" XFT_NMISSING            used in xftcore.c, xftextent.c, xftglyphs.c,
 .\"                                 xftrender.c
 .SH "DATA TYPES"
@@ -443,6 +447,169 @@ The
 .B FT_UInt
 data type is defined by the FreeType library.
 .SH FUNCTIONS
+.\" *************************************************************************
+.SS "Initialization"
+A typical application using Xft does not explicitly initialize the library.
+That is usually done as a side-effect of opening a font.
+.PP
+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.
+.PP
+Not all of the collected information is stored in a pattern.
+The remainer is stored in internal data structures.
+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 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 Xft will use for this display.
+.IP
+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 Xft
+(default: 4*1024*1024).
+.TP 5
+XFT_MAX_UNREF_FONTS
+(maxunreffonts).
+This is the maximum number of unreferenced fonts
+(default: 16).
+.RE
+.IP
+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
+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 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
+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
+Xft calls
+.BR XftInitFtLibrary ()
+internally via
+.BR XftFontInfoCreate "() and"
+.BR XftFontOpenPattern ().
+.IP
+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 Xft which is in use.
+.\" *************************************************************************
 .SS "Opening and Matching Fonts"
 .PS
 \fBXftFont\fP *\fBXftFontOpen\fP (
@@ -519,6 +686,7 @@ The
 and
 .B FcResult
 data types are defined by the Fontconfig library.
+.\" *************************************************************************
 .SS "Determining the Pixel Extents of a Text String"
 .PS
 \fBvoid\fP \fBXftTextExtents8\fP (
@@ -675,6 +843,7 @@ The
 data type is defined by the FreeType library, and the
 .B XGlyphInfo
 data type is defined by the X Rendering Extension library.
+.\" *************************************************************************
 .SS "Drawing Strings (and Other Things)"
 .PS
 \fBXftDraw\fP *\fBXftDrawCreate\fP (
@@ -863,6 +1032,7 @@ does provide 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"