document the clipping-functions

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

1 files changed, 204 insertions, 33 deletions

diff --git a/man/Xft.man b/man/Xft.man
index a58d702..247690e 100644
--- a/man/Xft.man
+++ b/man/Xft.man
@@ -126,11 +126,37 @@ version constants might be used:
     #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 From Xlib...
+Xlib datatypes do not follow a naming convention.
+They are documented in
+.I Xlib \- C Language Interface
+.TP 5
+.B Region
+Declared in \fI<X11/Xutil.h>\fP and \fI<X11/Xregion.h>\fP,
+a
+.B Region
+is an arbitrary set of pixel locations which Xlib can manipulate.
+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.
+.SS From XRender...
+XRender datatypes are inspired by Xlib,
+but lack the corresponding documentation.
+.SS From Fontconfig...
+Fontconfig datatypes follow a naming convention,
+prefixing all names with \*(``Fc\*('' which are documented in
+.I Fontconfig Developers Reference
+.SS From FreeType 2...
+FreeType 2 datatypes follow a naming convention,
+prefixing all names with \*(``FT_\*('' which are documented in
+.I FreeType API Reference
 .SS XftFont
+Xft datatypes follow a naming convention,
+prefixing all names with \*(``Xft\*(''
 .QS
 typedef struct _XftFont {
 	int	 ascent;
@@ -461,7 +487,7 @@ 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 
+.B XRenderPictFormat
 (X Render's datatype which is analogous to Xlib's Visual)
 on the display.
 .PS
@@ -609,7 +635,7 @@ when it is done.
 .PS
 \fBint\fP \fBXftGetVersion\fP (\fBvoid\fP);
 .PE
-Returns \fBXftVersion\fP, enabling an application to determine the
+Return \fBXftVersion\fP, enabling an application to determine the
 actual version of
 .B Xft
 which is in use.
@@ -632,7 +658,8 @@ on display
 The
 .B Display
 data type is defined by the X11 library.
-Returns NULL if no match is found.
+Return the matched font, or
+NULL if no match is found.
 .PP
 Example:
 .QS
@@ -716,8 +743,8 @@ and
 .IP
 .B XftXlfdParse
 creates a Fontconfig pattern,
-setting
-.I XFT_XLFD
+setting the property
+.B XFT_XLFD
 to the
 .I xlfd_orig
 value,
@@ -750,7 +777,7 @@ from
 .IR point_size .
 .TP 5
 FC_PIXEL_SIZE
-from 
+from
 .IR pixel_size .
 If
 .I point_size
@@ -933,7 +960,7 @@ the corresponding entry in
 .I extents
 is filled with zeroes.
 .\" *************************************************************************
-.SS "Drawing Strings (and Other Things)"
+.SS "Managing XftDraw"
 .PS
 \fBXftDraw\fP *\fBXftDrawCreate\fP (
 	\fBDisplay\fP	*\fIdpy\fP,
@@ -950,6 +977,7 @@ and
 .I colormap
 on
 .IR display .
+.IP
 The
 .BR Drawable ,
 .BR Visual ,
@@ -965,7 +993,8 @@ data types are defined by the X11 library.
 .B XftDrawCreateBitmap
 behaves as
 .BR XftDrawCreate (),
-except it uses an X pixmap of color depth 1 instead of an X drawable.
+except that it uses an X pixmap of color depth 1 instead of an X drawable.
+.IP
 The
 .B Pixmap
 data type is defined by the X11 library.
@@ -979,9 +1008,10 @@ data type is defined by the X11 library.
 .B XftDrawCreateAlpha
 behaves as
 .BR XftDrawCreate (),
-except it uses an X pixmap of color depth
+except that it uses an X pixmap of color depth
 .I depth
 instead of an X drawable.
+.IP
 The
 .B Pixmap
 data type is defined by the X11 library.
@@ -1048,6 +1078,7 @@ returns the picture associated with the
 .B Xft
 draw object
 .IR draw .
+.IP
 If the the X server does not support the X Rendering Extension, 0 is
 returned.
 .PP
@@ -1056,18 +1087,25 @@ returned.
 	\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
+Return an X Render Picture object,
+which is used for rendering glyphs,
+e.g., with
+.BR XftGlyphRender (),
+.BR XftGlyphSpecRender (),
+or
+.BR XftGlyphFontSpecRender (),
+by
+.BR XftDrawGlyphs (),
+.BR XftDrawGlyphSpec (),
+.BR XftDrawGlyphFontSpec (),
+respectively.
+.IP
+If the X server does not support the X Render extension,
+those functions use
+.BR XftGlyphCore (),
+.BR XftGlyphSpecCore (),
+or
+.BR XftGlyphFontSpecCore ().
 .PS
 \fBvoid\fP \fBXftDrawDestroy\fP (
 	\fBXftDraw\fP	*\fIdraw\fP);
@@ -1076,9 +1114,140 @@ is used.
 destroys
 .I draw
 (created by one of the
-.B XftCreate
+.BR XftDrawCreate *()
 functions) and frees the memory that was allocated for it.
-.PP
+.PS
+\fBBool\fP \fBXftDrawSetClip\fP (
+	\fBXftDraw\fP	*\fIdraw\fP,
+	\fBRegion\fP	 \fIr\fP);
+.PE
+Set up clipping for the given
+.B XftDraw
+parameter
+.I draw
+starting with a
+.BR Region :
+.RS 7
+.bP
+If the
+.B Region
+parameter
+.I r
+is not null,
+.B Xft
+creates a new
+.B Region
+(to copy the parameter),
+.bP
+.B Xft
+destroys any existing clipping region.
+.bP
+.B Xft
+sets the clip_type
+for the
+.I draw
+parameter to
+.B XftClipTypeRegion
+if the
+.I r
+parameter was not null.
+Otherwise it sets the clip_type to
+.BR XftClipTypeNone .
+.bP
+Finally,
+.B Xft
+updates clipping for existing objects,
+updates the clip_mask for its X Render
+.B Picture
+object
+and sets the clipping-mask in the graphic context (GC) associated with the
+.B XftDraw
+parameter.
+.RE
+.IP
+.BR XftDrawSetClip ()
+returns
+.B True
+if no change was necessary, or if the operation succeeded.
+It returns
+.B False
+if it was unable to create the new
+.BR Region ().
+.PS
+\fBBool\fP \fBXftDrawSetClipRectangles\fP (
+	\fBXftDraw\fP	*\fIdraw\fP,
+	\fBint\fP	 \fIxOrigin\fP,
+	\fBint\fP	 \fIyOrigin\fP,
+	\fB_Xconst XRectangle\fP	*\fIrects\fP,
+	\fBint\fP	 \fIn\fP);
+.PE
+Like
+.BR XftDrawSetClip (),
+.B XftDrawSetClipRectangles()
+sets up clipping for the given
+.B XftDraw
+parameter
+.I draw
+but uses a set of
+.I n
+rectangles (the
+.I rects
+parameter)
+which could be used to construct a
+.B Region .
+.IP
+.B Xft
+sets the clip_type for
+.I draw
+to
+XftClipTypeRectangles
+and uses
+.BR XSetClipRectangles ()
+for core (X11) clipping
+and
+.BR XRenderSetPictureClipRectangles ()
+for X Render clipping.
+.PS
+\fBvoid\fP \fBXftDrawSetSubwindowMode\fP (
+	\fBXftDraw\fP	*\fIdraw\fP,
+	\fBint\fP	 \fImode\fP);
+.PE
+Sets the subwindow-mode for the given
+.B XftDraw
+parameter
+.IR draw .
+The mode can be either
+.B ClipByChildren
+(the default), or
+.BR IncludeInferiors :
+.RS 7
+.bP
+For
+.BR ClipByChildren ,
+both source and destination windows are
+additionally clipped by all viewable
+.B InputOutput
+children.
+.bP
+For
+.BR IncludeInferiors ,
+neither source nor destination window is clipped by inferiors.
+This will result in including subwindow contents in the source
+and drawing through subwindow boundaries of the destination.
+.RE
+.IP
+In addition to the subwindow-mode maintained by
+.BR Xft ,
+it updates the subwindow mode for any associated graphics context
+.B GC
+using
+.BR XSetSubwindowMode ()
+as well as for an X Render
+.B Picture
+using
+.BR XRenderChangePicture ().
+.\" *************************************************************************
+.SS "Drawing Strings"
 .PS
 \fBvoid\fP \fBXftDrawString8\fP (
 	\fBXftDraw\fP	*\fId\fP,
@@ -1104,7 +1273,8 @@ in
 .I color
 at position
 .IR x , " y" .
-.PP
+.\" *************************************************************************
+.SS "Drawing Other Things"
 .PS
 \fBvoid\fP \fBXftDrawRect\fP (
 	\fBXftDraw\fP	*\fId\fP,
@@ -1126,6 +1296,7 @@ to
 .B Xft
 drawable
 .IR d .
+.\" *************************************************************************
 .SS Manipulating patterns
 .PS
 \fBFcFontSet\fP *\fBXftListFonts\fP (
@@ -1196,7 +1367,7 @@ otherwise it returns
 Using
 .BR FT_Load_Glyph (),
 load
-.I nglyphs 
+.I nglyphs
 for the glyph indices (Unicode values)
 listed in the array
 .I glyphs
@@ -1206,13 +1377,13 @@ from the given font
 Loading a glyph entails more than just reading data into memory.
 .B Xft
 uses the Fontconfig pattern associated with the display
-.I dpy 
+.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
+compute font metrics, and
 add it to the
 X Render extension using
 .BR XRenderAddGlyphs ().
@@ -1279,7 +1450,7 @@ objects are deallocated using
 .B Xft
 does this in
 .BR XftFontInfoDestroy ()
-and when cleaning up on failure in 
+and when cleaning up on failure in
 .BR XftFontInfoCreate ()
 and
 .BR XftFontOpenPattern ().
@@ -1295,10 +1466,10 @@ Xft
 .RI 1. x ,
 described below.
 .\" *************************************************************************
-.SS "Xft 1.x Compatibility Header File"
+.SS "Xft 1.x Header File"
 .B #include <X11/Xft/XftCompat.h>
-.\" .SS "Xft 1.x Compatibility Constants"
-.SS "Xft 1.x Compatibility Data Types"
+.\" .SS "Xft 1.x Constants"
+.SS "Xft 1.x Data Types"
 .TP
 .B XftPattern
 holds a set of names with associated value lists; each name refers to a
@@ -1320,7 +1491,7 @@ returns the results of listing fonts in this format.
 .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"
+.\" .SS "Xft 1.x Functions"
 .SH AUTHOR
 Keith Packard
 .SH "SEE ALSO"