From 58b1fed139c6dfd1a20a8b6090181f43aaffcc59 Mon Sep 17 00:00:00 2001 From: "Thomas E. Dickey" Date: Fri, 10 Jun 2022 09:27:36 -0400 Subject: document the clipping-functions Signed-off-by: Thomas E. Dickey --- man/Xft.man | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file 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\fP and \fI\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 -.\" .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" -- cgit v1.2.1