add section on manipulating font data

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

1 files changed, 105 insertions, 4 deletions

diff --git a/man/Xft.man b/man/Xft.man
index 32aa182..a58d702 100644
--- a/man/Xft.man
+++ b/man/Xft.man
@@ -1184,14 +1184,113 @@ 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,
+As of version 2 (May 2002),
 .B Xft
-has become relatively stable and is expected to retain source and binary
-compatibility in future releases.
+became relatively stable.
+It is expected to retain source and binary compatibility in future releases.
 .PP
 .B Xft
-does provide a compatibility interface to its previous major version,
+provides a compatibility interface to its previous major version,
 Xft
 .RI 1. x ,
 described below.
@@ -1230,6 +1329,8 @@ Keith Packard
 .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