document XftGlyphFontSpecRender() and related functions.

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

1 files changed, 156 insertions, 1 deletions

diff --git a/man/Xft.man b/man/Xft.man
index b4c1370..99c1207 100644
--- a/man/Xft.man
+++ b/man/Xft.man
@@ -146,6 +146,21 @@ Pixmap,
 Region,
 Visual, and
 XRectangle.
+.PP
+Some datatypes are especially relevant to
+.BR Xft :
+.TP 5
+.B Drawable
+Declared in \fI<X11/X.h>\fP,
+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
+.B InputOnly
+window cannot be used as a source or destination in a
+graphics operation.
 .TP 5
 .B Region
 Declared in \fI<X11/Xutil.h>\fP and \fI<X11/Xregion.h>\fP,
@@ -156,6 +171,10 @@ Internally, a
 .B Region
 is represented by the union of an arbitrary number of rectangles.
 Xlib maintains a rectangle which tells it the extent of this union.
+.TP 5
+.B Visual
+Declared in \fI<X11/Xutil.h>\fP,
+this structure contains information about the possible color mapping.
 .SS From XRender...
 The X Render Extension library
 datatypes are inspired by Xlib,
@@ -166,6 +185,8 @@ Refer to the header file for details:
 .I <X11/extensions/Xrender.h>
 .RE
 .PP
+or read the source code (which provides an outline of libXrender).
+.PP
 .B Xft
 uses these names:
 Picture,
@@ -447,7 +468,6 @@ typedef struct _XftCharSpec {
 } XftCharSpec;
 .QE
 .PP
-The
 .B XftCharSpec
 is used by
 .BR XftDrawCharSpec (),
@@ -464,6 +484,9 @@ typedef struct _XftCharFontSpec {
 } XftCharFontSpec;
 .QE
 .PP
+.B XftCharFontSpec
+is used by
+.BR XftCharFontSpecRender ().
 .SS
 .B XftGlyphSpec
 .QS
@@ -473,6 +496,10 @@ typedef struct _XftGlyphSpec {
 	short	  y;
 } XftGlyphSpec;
 .QE
+.PP
+.B XftGlyphSpec
+is used by
+.BR XftDrawGlyphSpec ().
 .SS XftGlyphFontSpec
 .QS
 typedef struct _XftGlyphFontSpec {
@@ -482,6 +509,12 @@ typedef struct _XftGlyphFontSpec {
 	short	 y;
 } XftGlyphFontSpec;
 .QE
+.PP
+.B XftGlyphFontSpec
+is used by
+.BR XftDrawGlyphFontSpec (),
+and
+.BR XftGlyphFontSpecRender ().
 .SH FUNCTIONS
 .\" *************************************************************************
 .SS "Initialization"
@@ -1289,6 +1322,128 @@ to
 .B Xft
 drawable
 .IR d .
+.PS
+\fBvoid\fP \fBXftCharFontSpecRender\fP (
+	\fBDisplay\fP	*\fIdpy\fP,
+	\fBint\fP	 \fIop\fP,
+	\fBPicture\fP	 \fIsrc\fP,
+	\fBPicture\fP	 \fIdst\fP,
+	\fBint\fP	 \fIsrcx\fP,
+	\fBint\fP	 \fIsrcy\fP,
+	\fB_Xconst XftCharFontSpec\fP	*\fIchars\fP,
+	\fBint\fP	 \fIlen\fP);
+.PE
+.BR XftCharFontSpecRender ()
+converts the
+.I chars
+parameter from
+.B XftCharFontSpec
+to
+.BR XftGlyphFontSpec ,
+passing the converted array along with the other parameters unchanged to
+.BR XftGlyphFontSpecRender ()
+to render the data.
+.PS
+\fBvoid\fP \fBXftDrawGlyphFontSpec\fP (
+	\fBXftDraw\fP	*\fIdraw\fP,
+	\fB_Xconst XftColor\fP	*\fIcolor\fP,
+	\fB_Xconst XftGlyphFontSpec\fP	*\fIglyphs\fP,
+	\fBint\fP	 \fIlen\fP);
+.PE
+Draw a list of glyphs associated with fonts at specified coordinates,
+passed as an array of 
+.I len
+.B XftGlyphFontSpec
+structures via the parameter
+.IR glyphs .
+All of the glyphs are drawn using the color specified in the
+.I color
+parameter.
+.IP
+For each entry in the
+.I glyphs
+array:
+.RS 7
+.bP
+If the associated font uses the X Render extension, then
+.B Xft
+uses
+.BR XftGlyphFontSpecRender ()
+to draw the glyph,
+using a
+.B Picture
+obtained from calling
+.B XftDrawSrcPicture ()
+with the
+.I draw
+and
+.I color
+parameters.
+.bP
+Otherwise,
+.B Xft
+provides an analogous feature using Xlib.
+.RE
+.PS
+\fBvoid\fP \fBXftGlyphFontSpecRender\fP (
+	\fBDisplay\fP	*\fIdpy\fP,
+	\fBint\fP	 \fIop\fP,
+	\fBPicture\fP	 \fIsrc\fP,
+	\fBPicture\fP	 \fIdst\fP,
+	\fBint\fP	 \fIsrcx\fP,
+	\fBint\fP	 \fIsrcy\fP,
+	\fB_Xconst XftGlyphFontSpec\fP	*\fIglyphs\fP,
+	\fBint\fP	 \fInglyphs\fP);
+.PE
+This involves several steps:
+.RS 7
+.bP
+First,
+.B Xft
+ensures that the
+.I glyphs
+array is complete using
+.BR XftFontCheckGlyph ()
+and loading any missing glyphs with
+.BR XftFontLoadGlyphs ().
+.bP
+Then
+.B Xft
+examines the glyphs to find the maximum Unicode value.
+That determines the encoding size, i.e., the
+.IR width .
+.bP
+Then, for each glyph,
+.B 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,
+.B Xft
+also remembers which was the first font used,
+and computes the position at which each glyph will be drawn.
+.bP
+.B Xft
+then constructs an equivalent array of glyphs in the format expected by
+the X Render library.
+.bP
+Finally,
+.BR XftGlyphFontSpecRender ()
+uses the X Render extension to draw the glyphs,
+with the appropriate 
+.BR XRenderCompositeText *()
+function according to the
+.IR width ,
+and discards temporary data.
+.IP
+The
+.IR op ,
+.IR dst ,
+.IR src ,
+.IR srcx ,
+and
+.I srcy
+parameters are used as described in the documentation for the X Render library.
+.RE
 .\" *************************************************************************
 .SS Manipulating patterns
 .PS