diff options
Diffstat (limited to 'libX11/specs/libX11/CH07')
| -rw-r--r-- | libX11/specs/libX11/CH07 | 2357 |
1 files changed, 2357 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH07 b/libX11/specs/libX11/CH07 new file mode 100644 index 000000000..d6f672289 --- /dev/null +++ b/libX11/specs/libX11/CH07 @@ -0,0 +1,2357 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 7\fP\s-1 + +\s+1\fBGraphics Context Functions\fP\s-1 +.sp 2 +.nr H1 7 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 7: Graphics Context Functions +.XE +A number of resources are used when performing graphics operations in X. +Most information about performing graphics (for example, foreground +color, background color, line style, and so on) is stored in +resources called graphics contexts (GCs). +.IN "Graphics context" +Most graphics operations (see chapter 8) take a +GC as an argument. +Although in theory the X protocol permits sharing of GCs between applications, +it is expected that applications will use their own +GCs when performing operations. +Sharing of GCs is highly discouraged because the library may cache GC state. +.LP +Graphics operations can be performed to either windows or pixmaps, +which collectively are called drawables. +.IN "Root" +Each drawable exists on a single screen. +A GC is created for a specific screen and drawable depth +and can only be used with drawables of matching +screen and depth. +.LP +This chapter discusses how to: +.IP \(bu 5 +Manipulate graphics context/state +.IP \(bu 5 +Use graphics context convenience functions +.NH 2 +Manipulating Graphics Context/State +.XS +\*(SN Manipulating Graphics Context/State +.XE +.LP +Most attributes of graphics operations are stored in GCs. +These include line width, line style, plane mask, foreground, background, +tile, stipple, clipping region, end style, join style, and so on. +Graphics operations (for example, drawing lines) use these values +to determine the actual drawing operation. +Extensions to X may add additional components to GCs. +The contents of a GC are private to Xlib. +.LP +Xlib implements a write-back cache for all elements of a GC that are not +resource IDs to allow Xlib to implement the transparent coalescing of changes +to GCs. +For example, +a call to +.PN XSetForeground +of a GC followed by a call to +.PN XSetLineAttributes +results in only a single-change GC protocol request to the server. +GCs are neither expected nor encouraged to be shared between client +applications, so this write-back caching should present no problems. +Applications cannot share GCs without external synchronization. +Therefore, +sharing GCs between applications is highly discouraged. +.LP +To set an attribute of a GC, +set the appropriate member of the +.PN XGCValues +structure and OR in the corresponding value bitmask in your subsequent calls to +.PN XCreateGC . +The symbols for the value mask bits and the +.PN XGCValues +structure are: +.sM +.LP +/* GC attribute value mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.75i). +#define\ + T{ +.PN GCFunction +T} T{ +(1L<<0) +T} +#define\ + T{ +.PN GCPlaneMask +T} T{ +(1L<<1) +T} +#define\ + T{ +.PN GCForeground +T} T{ +(1L<<2) +T} +#define\ + T{ +.PN GCBackground +T} T{ +(1L<<3) +T} +#define\ + T{ +.PN GCLineWidth +T} T{ +(1L<<4) +T} +#define\ + T{ +.PN GCLineStyle +T} T{ +(1L<<5) +T} +#define\ + T{ +.PN GCCapStyle +T} T{ +(1L<<6) +T} +#define\ + T{ +.PN GCJoinStyle +T} T{ +(1L<<7) +T} +#define\ + T{ +.PN GCFillStyle +T} T{ +(1L<<8) +T} +#define\ + T{ +.PN GCFillRule +T} T{ +(1L<<9) +T} +#define\ + T{ +.PN GCTile +T} T{ +(1L<<10) +T} +#define\ + T{ +.PN GCStipple +T} T{ +(1L<<11) +T} +#define\ + T{ +.PN GCTileStipXOrigin +T} T{ +(1L<<12) +T} +#define\ + T{ +.PN GCTileStipYOrigin +T} T{ +(1L<<13) +T} +#define\ + T{ +.PN GCFont +T} T{ +(1L<<14) +T} +#define\ + T{ +.PN GCSubwindowMode +T} T{ +(1L<<15) +T} +#define\ + T{ +.PN GCGraphicsExposures +T} T{ +(1L<<16) +T} +#define\ + T{ +.PN GCClipXOrigin +T} T{ +(1L<<17) +T} +#define\ + T{ +.PN GCClipYOrigin +T} T{ +(1L<<18) +T} +#define\ + T{ +.PN GCClipMask +T} T{ +(1L<<19) +T} +#define\ + T{ +.PN GCDashOffset +T} T{ +(1L<<20) +T} +#define\ + T{ +.PN GCDashList +T} T{ +(1L<<21) +T} +#define\ + T{ +.PN GCArcMode +T} T{ +(1L<<22) +T} +.TE +.IN "XGCValues" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + int function; /* logical operation */ + unsigned long plane_mask; /* plane mask */ + unsigned long foreground; /* foreground pixel */ + unsigned long background; /* background pixel */ + int line_width; /* line width (in pixels) */ + int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ + int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ + int join_style; /* JoinMiter, JoinRound, JoinBevel */ + int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/ + int fill_rule; /* EvenOddRule, WindingRule */ + int arc_mode; /* ArcChord, ArcPieSlice */ + Pixmap tile; /* tile pixmap for tiling operations */ + Pixmap stipple; /* stipple 1 plane pixmap for stippling */ + int ts_x_origin; /* offset for tile or stipple operations */ + int ts_y_origin; + Font font; /* default text font for text operations */ + int subwindow_mode; /* ClipByChildren, IncludeInferiors */ + Bool graphics_exposures; /* boolean, should exposures be generated */ + int clip_x_origin; /* origin for clipping */ + int clip_y_origin; + Pixmap clip_mask; /* bitmap clipping; other calls for rects */ + int dash_offset; /* patterned/dashed line information */ + char dashes; +} XGCValues; +.De +.LP +.eM +The default GC values are: +.TS H +l l. +_ +.sp 6p +.B +Component Default +.sp 6p +_ +.sp 6p +.TH +.R +T{ +function +T} T{ +.PN GXcopy +T} +plane_mask All ones +foreground 0 +background 1 +line_width 0 +T{ +line_style +T} T{ +.PN LineSolid +T} +T{ +cap_style +T} T{ +.PN CapButt +T} +T{ +join_style +T} T{ +.PN JoinMiter +T} +T{ +fill_style +T} T{ +.PN FillSolid +T} +T{ +fill_rule +T} T{ +.PN EvenOddRule +T} +T{ +arc_mode +T} T{ +.PN ArcPieSlice +T} +tile Pixmap of unspecified size filled with foreground pixel + (that is, client specified pixel if any, else 0) + (subsequent changes to foreground do not affect this pixmap) +stipple Pixmap of unspecified size filled with ones +ts_x_origin 0 +ts_y_origin 0 +font <implementation dependent> +T{ +subwindow_mode +T} T{ +.PN ClipByChildren +T} +T{ +graphics_exposures +T} T{ +.PN True +T} +clip_x_origin 0 +clip_y_origin 0 +T{ +clip_mask +T} T{ +.PN None +T} +dash_offset 0 +dashes 4 (that is, the list [4, 4]) +.sp 6p +_ +.TE +.LP +Note that foreground and background are not set to any values likely +to be useful in a window. +.LP +.IN "Display Functions" "" "@DEF@" +.IN "Source" "" "@DEF@" +.IN "Destination" "" "@DEF@" +The function attributes of a GC are used when you update a section of +a drawable (the destination) with bits from somewhere else (the source). +The function in a GC defines how the new destination bits are to be +computed from the source bits and the old destination bits. +.PN GXcopy +is typically the most useful because it will work on a color display, +but special applications may use other functions, +particularly in concert with particular planes of a color display. +The 16 GC functions, defined in +.hN X11/X.h , +are: +.\" are listed in Table 5-1 along with the +.\"the associated hexadecimal code +.\" and operation. +.\".CP T 1 +.\"Display Functions +.TS H +lw(1.5i) cw(.5i) lw(2i). +_ +.sp 6p +.B +Function Name Value Operation +.sp 6p +_ +.sp 6p +.TH +T{ +.PN GXclear +T} T{ +0x0 +T} T{ +0 +T} +T{ +.PN GXand +T} T{ +0x1 +T} T{ +src AND dst +T} +T{ +.PN GXandReverse +T} T{ +0x2 +T} T{ +src AND NOT dst +T} +T{ +.PN GXcopy +T} T{ +0x3 +T} T{ +src +T} +T{ +.PN GXandInverted +T} T{ +0x4 +T} T{ +(NOT src) AND dst +T} +T{ +.PN GXnoop +T} T{ +0x5 +T} T{ +dst +T} +T{ +.PN GXxor +T} T{ +0x6 +T} T{ +src XOR dst +T} +T{ +.PN GXor +T} T{ +0x7 +T} T{ +src OR dst +T} +T{ +.PN GXnor +T} T{ +0x8 +T} T{ +(NOT src) AND (NOT dst) +T} +T{ +.PN GXequiv +T} T{ +0x9 +T} T{ +(NOT src) XOR dst +T} +T{ +.PN GXinvert +T} T{ +0xa +T} T{ +NOT dst +T} +T{ +.PN GXorReverse +T} T{ +0xb +T} T{ +src OR (NOT dst) +T} +T{ +.PN GXcopyInverted +T} T{ +0xc +T} T{ +NOT src +T} +T{ +.PN GXorInverted +T} T{ +0xd +T} T{ +(NOT src) OR dst +T} +T{ +.PN GXnand +T} T{ +0xe +T} T{ +(NOT src) OR (NOT dst) +T} +T{ +.PN GXset +T} T{ +0xf +T} T{ +1 +T} +.sp 6p +_ +.TE +.LP +Many graphics operations depend on either pixel values or planes in a GC. +.IN "Pixel value" +The planes attribute is of type long, and it specifies which planes of the +destination are to be modified, one bit per plane. +.IN "Plane" "mask" +A monochrome display has only one plane and +will be the least significant bit of the word. +As planes are added to the display hardware, they will occupy more +significant bits in the plane mask. +.LP +In graphics operations, given a source and destination pixel, +the result is computed bitwise on corresponding bits of the pixels. +That is, a Boolean operation is performed in each bit plane. +The plane_mask restricts the operation to a subset of planes. +A macro constant +.PN AllPlanes +can be used to refer to all planes of the screen simultaneously. +The result is computed by the following: +.LP +.Ds +((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) +.De +.LP +Range checking is not performed on the values for foreground, +background, or plane_mask. +They are simply truncated to the appropriate +number of bits. +The line-width is measured in pixels and either can be greater than or equal to +one (wide line) or can be the special value zero (thin line). +.LP +Wide lines are drawn centered on the path described by the graphics request. +Unless otherwise specified by the join-style or cap-style, +the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and +width w is a rectangle with vertices at the following real coordinates: +.LP +.Ds +.TA .5i 2.5i +.ta .5i 2.5i +[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], +[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] +.De +.LP +Here sn is the sine of the angle of the line, +and cs is the cosine of the angle of the line. +A pixel is part of the line and so is drawn +if the center of the pixel is fully inside the bounding box +(which is viewed as having infinitely thin edges). +If the center of the pixel is exactly on the bounding box, +it is part of the line if and only if the interior is immediately to its right +(x increasing direction). +Pixels with centers on a horizontal edge are a special case and are part of +the line if and only if the interior or the boundary is immediately below +(y increasing direction) and the interior or the boundary is immediately +to the right (x increasing direction). +.LP +Thin lines (zero line-width) are one-pixel-wide lines drawn using an +unspecified, device-dependent algorithm. +There are only two constraints on this algorithm. +.IP 1. 5 +If a line is drawn unclipped from [x1,y1] to [x2,y2] and +if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], +a point [x,y] is touched by drawing the first line +if and only if the point [x+dx,y+dy] is touched by drawing the second line. +.IP 2. 5 +The effective set of points comprising a line cannot be affected by clipping. +That is, a point is touched in a clipped line if and only if the point +lies inside the clipping region and the point would be touched +by the line when drawn unclipped. +.LP +A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels +as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style +and join-style. +It is recommended that this property be true for thin lines, +but this is not required. +A line-width of zero may differ from a line-width of one in which pixels are +drawn. +This permits the use of many manufacturers' line drawing hardware, +which may run many times faster than the more precisely specified +wide lines. +.LP +In general, +drawing a thin line will be faster than drawing a wide line of width one. +However, because of their different drawing algorithms, +thin lines may not mix well aesthetically with wide lines. +If it is desirable to obtain precise and uniform results across all displays, +a client should always use a line-width of one rather than a line-width of zero. +.LP +The line-style defines which sections of a line are drawn: +.TS +lw(1.3i) lw(4.5i). +T{ +.PN LineSolid +T} T{ +The full path of the line is drawn. +T} +.sp 6p +T{ +.PN LineDoubleDash +T} T{ +The full path of the line is drawn, +but the even dashes are filled differently +from the odd dashes (see fill-style) with +.PN CapButt +style used where even and odd dashes meet. +T} +.sp 6p +T{ +.PN LineOnOffDash +T} T{ +Only the even dashes are drawn, +and cap-style applies to +all internal ends of the individual dashes, +except +.PN CapNotLast +is treated as +.PN CapButt . +T} +.TE +.LP +The cap-style defines how the endpoints of a path are drawn: +.IN "Graphics context" "path" +.TS +lw(1.3i) lw(4.5i). +T{ +.PN CapNotLast +T} T{ +This is equivalent to +.PN CapButt +except that for a line-width of zero the final endpoint is not drawn. +T} +.sp 6p +T{ +.PN CapButt +T} T{ +The line is square at the endpoint (perpendicular to the slope of the line) +with no projection beyond. +T} +.sp 6p +T{ +.PN CapRound +T} T{ +The line has a circular arc with the diameter equal to the line-width, +centered on the endpoint. +(This is equivalent to +.PN CapButt +for line-width of zero). +T} +.sp 6p +T{ +.PN CapProjecting +T} T{ +The line is square at the end, but the path continues beyond the endpoint +for a distance equal to half the line-width. +(This is equivalent to +.PN CapButt +for line-width of zero). +T} +.TE +.LP +The join-style defines how corners are drawn for wide lines: +.TS +lw(1.3i) lw(4.5i). +T{ +.PN JoinMiter +T} T{ +The outer edges of two lines extend to meet at an angle. +However, if the angle is less than 11 degrees, +then a +.PN JoinBevel +join-style is used instead. +T} +.sp 6p +T{ +.PN JoinRound +T} T{ +The corner is a circular arc with the diameter equal to the line-width, +centered on the joinpoint. +T} +.sp 6p +T{ +.PN JoinBevel +T} T{ +The corner has +.PN CapButt +endpoint styles with the triangular notch filled. +T} +.TE +.LP +For a line with coincident endpoints (x1=x2, y1=y2), +when the cap-style is applied to both endpoints, +the semantics depends on the line-width and the cap-style: +.TS +lw(1.3i) lw(.5i) lw(4i). +T{ +.PN CapNotLast +T} T{ +thin +T} T{ +The results are device dependent, +but the desired effect is that nothing is drawn. +T} +.sp 6p +T{ +.PN CapButt +T} T{ +thin +T} T{ +The results are device dependent, +but the desired effect is that a single pixel is drawn. +T} +.sp 6p +T{ +.PN CapRound +T} T{ +thin +T} T{ +The results are the same as for +.PN CapButt /thin. +T} +.sp 6p +T{ +.PN CapProjecting +T} T{ +thin +T} T{ +The results are the same as for +.PN CapButt /thin. +T} +.sp 6p +T{ +.PN CapButt +T} T{ +wide +T} T{ +Nothing is drawn. +T} +.sp 6p +T{ +.PN CapRound +T} T{ +wide +T} T{ +The closed path is a circle, centered at the endpoint, and +with the diameter equal to the line-width. +T} +.sp 6p +T{ +.PN CapProjecting +T} T{ +wide +T} T{ +The closed path is a square, aligned with the coordinate axes, centered at the +endpoint, and with the sides equal to the line-width. +T} +.TE +.LP +For a line with coincident endpoints (x1=x2, y1=y2), +when the join-style is applied at one or both endpoints, +the effect is as if the line was removed from the overall path. +However, if the total path consists of or is reduced to a single point joined +with itself, the effect is the same as when the cap-style is applied at both +endpoints. +.LP +The tile/stipple represents an infinite two-dimensional plane, +with the tile/stipple replicated in all dimensions. +When that plane is superimposed on the drawable +for use in a graphics operation, the upper-left corner +of some instance of the tile/stipple is at the coordinates within +the drawable specified by the tile/stipple origin. +The tile/stipple and clip origins are interpreted relative to the +origin of whatever destination drawable is specified in a graphics +request. +The tile pixmap must have the same root and depth as the GC, +or a +.PN BadMatch +error results. +The stipple pixmap must have depth one and must have the same root as the +GC, or a +.PN BadMatch +error results. +For stipple operations where the fill-style is +.PN FillStippled +but not +.PN FillOpaqueStippled , +the stipple pattern is tiled in a +single plane and acts as an additional clip mask to be ANDed with the clip-mask. +Although some sizes may be faster to use than others, +any size pixmap can be used for tiling or stippling. +.LP +The fill-style defines the contents of the source for line, text, and +fill requests. +For all text and fill requests (for example, +.PN XDrawText , +.PN XDrawText16 , +.PN XFillRectangle , +.PN XFillPolygon , +and +.PN XFillArc ); +for line requests +with line-style +.PN LineSolid +(for example, +.PN XDrawLine , +.PN XDrawSegments , +.PN XDrawRectangle , +.PN XDrawArc ); +and for the even dashes for line requests with line-style +.PN LineOnOffDash +or +.PN LineDoubleDash , +the following apply: +.TS +lw(1.8i) lw(4i). +T{ +.PN FillSolid +T} T{ +Foreground +T} +.sp 6p +T{ +.PN FillTiled +T} T{ +Tile +T} +.sp 6p +T{ +.PN FillOpaqueStippled +T} T{ +A tile with the same width and height as stipple, +but with background everywhere stipple has a zero +and with foreground everywhere stipple has a one +T} +.sp 6p +T{ +.PN FillStippled +T} T{ +Foreground masked by stipple +T} +.TE +.LP +When drawing lines with line-style +.PN LineDoubleDash , +the odd dashes are controlled by the fill-style in the following manner: +.TS +lw(1.8i) lw(4i). +T{ +.PN FillSolid +T} T{ +Background +T} +.sp 6p +T{ +.PN FillTiled +T} T{ +Same as for even dashes +T} +.sp 6p +T{ +.PN FillOpaqueStippled +T} T{ +Same as for even dashes +T} +.sp 6p +T{ +.PN FillStippled +T} T{ +Background masked by stipple +T} +.TE +.LP +Storing a pixmap in a GC might or might not result in a copy +being made. +If the pixmap is later used as the destination for a graphics request, +the change might or might not be reflected in the GC. +If the pixmap is used simultaneously in a graphics request both as +a destination and as a tile or stipple, +the results are undefined. +.LP +For optimum performance, +you should draw as much as possible with the same GC +(without changing its components). +The costs of changing GC components relative to using different GCs +depend on the display hardware and the server implementation. +It is quite likely that some amount of GC information will be +cached in display hardware and that such hardware can only cache a small number +of GCs. +.LP +The dashes value is actually a simplified form of the +more general patterns that can be set with +.PN XSetDashes . +Specifying a +value of N is equivalent to specifying the two-element list [N, N] in +.PN XSetDashes . +The value must be nonzero, +or a +.PN BadValue +error results. +.LP +The clip-mask restricts writes to the destination drawable. +If the clip-mask is set to a pixmap, +it must have depth one and have the same root as the GC, +or a +.PN BadMatch +error results. +If clip-mask is set to +.PN None , +the pixels are always drawn regardless of the clip origin. +The clip-mask also can be set by calling the +.PN XSetClipRectangles +or +.PN XSetRegion +functions. +Only pixels where the clip-mask has a bit set to 1 are drawn. +Pixels are not drawn outside the area covered by the clip-mask +or where the clip-mask has a bit set to 0. +The clip-mask affects all graphics requests. +The clip-mask does not clip sources. +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in a graphics request. +.LP +You can set the subwindow-mode to +.PN ClipByChildren +or +.PN IncludeInferiors . +For +.PN ClipByChildren , +both source and destination windows are +additionally clipped by all viewable +.PN InputOutput +children. +For +.PN 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. +The use of +.PN IncludeInferiors +on a window of one depth with mapped +inferiors of differing depth is not illegal, but the semantics are +undefined by the core protocol. +.LP +The fill-rule defines what pixels are inside (drawn) for +paths given in +.PN XFillPolygon +requests and can be set to +.PN EvenOddRule +or +.PN WindingRule . +For +.PN EvenOddRule , +a point is inside if +an infinite ray with the point as origin crosses the path an odd number +of times. +For +.PN WindingRule , +a point is inside if an infinite ray with the +point as origin crosses an unequal number of clockwise and +counterclockwise directed path segments. +A clockwise directed path segment is one that crosses the ray from left to +right as observed from the point. +A counterclockwise segment is one that crosses the ray from right to left +as observed from the point. +The case where a directed line segment is coincident with the ray is +uninteresting because you can simply choose a different ray that is not +coincident with a segment. +.LP +For both +.PN EvenOddRule +and +.PN WindingRule , +a point is infinitely small, +and the path is an infinitely thin line. +A pixel is inside if the center point of the pixel is inside +and the center point is not on the boundary. +If the center point is on the boundary, +the pixel is inside if and only if the polygon interior is immediately to +its right (x increasing direction). +Pixels with centers on a horizontal edge are a special case +and are inside if and only if the polygon interior is immediately below +(y increasing direction). +.LP +The arc-mode controls filling in the +.PN XFillArcs +function and can be set to +.PN ArcPieSlice +or +.PN ArcChord . +For +.PN ArcPieSlice , +the arcs are pie-slice filled. +For +.PN ArcChord , +the arcs are chord filled. +.LP +The graphics-exposure flag controls +.PN GraphicsExpose +event generation +for +.PN XCopyArea +and +.PN XCopyPlane +requests (and any similar requests defined by extensions). +.LP +.sp +To create a new GC that is usable on a given screen with a +depth of drawable, use +.PN XCreateGC . +.IN "Graphics context" "initializing" +.IN "XCreateGC" "" "@DEF@" +.sM +.FD 0 +GC XCreateGC\^(\^\fIdisplay\fP, \fId\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fId\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XGCValues *\^\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fId\fP 1i +Specifies the drawable. +.ds Vm set using the information in the specified values structure +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIvalues\fP 1i +Specifies any values as specified by the valuemask. +.LP +.eM +The +.PN XCreateGC +function creates a graphics context and returns a GC. +The GC can be used with any destination drawable having the same root +and depth as the specified drawable. +Use with other drawables results in a +.PN BadMatch +error. +.LP +.PN XCreateGC +can generate +.PN BadAlloc , +.PN BadDrawable , +.PN BadFont , +.PN BadMatch , +.PN BadPixmap , +and +.PN BadValue +errors. +.LP +.sp +To copy components from a source GC to a destination GC, use +.PN XCopyGC . +.IN "XCopyGC" "" "@DEF@" +.sM +.FD 0 +XCopyGC\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIvaluemask\fP\^, \fIdest\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIsrc\fP\^, \fIdest\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIsrc\fP 1i +Specifies the components of the source GC. +.ds Vm copied to the destination GC +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIdest\fP 1i +Specifies the destination GC. +.LP +.eM +The +.PN XCopyGC +function copies the specified components from the source GC +to the destination GC. +The source and destination GCs must have the same root and depth, +or a +.PN BadMatch +error results. +The valuemask specifies which component to copy, as for +.PN XCreateGC . +.LP +.PN XCopyGC +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadMatch +errors. +.LP +.sp +To change the components in a given GC, use +.PN XChangeGC . +.IN "XChangeGC" "" "@DEF@" +.sM +.FD 0 +XChangeGC\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XGCValues *\^\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Vm changed using information in the specified values structure +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIvalues\fP 1i +Specifies any values as specified by the valuemask. +.LP +.eM +The +.PN XChangeGC +function changes the components specified by valuemask for +the specified GC. +The values argument contains the values to be set. +The values and restrictions are the same as for +.PN XCreateGC . +Changing the clip-mask overrides any previous +.PN XSetClipRectangles +request on the context. +Changing the dash-offset or dash-list +overrides any previous +.PN XSetDashes +request on the context. +The order in which components are verified and altered is server dependent. +If an error is generated, a subset of the components may have been altered. +.LP +.PN XChangeGC +can generate +.PN BadAlloc , +.PN BadFont , +.PN BadGC , +.PN BadMatch , +.PN BadPixmap , +and +.PN BadValue +errors. +.LP +.sp +To obtain components of a given GC, use +.PN XGetGCValues . +.IN "XGetGCValues" "" "@DEF@" +.sM +.FD 0 +Status XGetGCValues\^(\^\fIdisplay\fP, \fIgc\fP, \fIvaluemask\fP, \ +\fIvalues_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XGCValues *\fIvalues_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.ds Vm returned in the values_return argument +.IP \fIvaluemask\fP 1i +Specifies which components in the GC are to be \*(Vm. +This argument is the bitwise inclusive OR of zero or more of the valid +GC component mask bits. +.IP \fIvalues_return\fP 1i +Returns the GC values in the specified +.PN XGCValues +structure. +.LP +.eM +The +.PN XGetGCValues +function returns the components specified by valuemask for the specified GC. +If the valuemask contains a valid set of GC mask bits +.Pn ( GCFunction , +.PN GCPlaneMask , +.PN GCForeground , +.PN GCBackground , +.PN GCLineWidth , +.PN GCLineStyle , +.PN GCCapStyle , +.PN GCJoinStyle , +.PN GCFillStyle , +.PN GCFillRule , +.PN GCTile , +.PN GCStipple , +.PN GCTileStipXOrigin , +.PN GCTileStipYOrigin , +.PN GCFont , +.PN GCSubwindowMode , +.PN GCGraphicsExposures , +.PN GCClipXOrigin , +.PN GCCLipYOrigin , +.PN GCDashOffset , +or +.PN GCArcMode ) +and no error occurs, +.PN XGetGCValues +sets the requested components in values_return and returns a nonzero status. +Otherwise, it returns a zero status. +Note that the clip-mask and dash-list (represented by the +.PN GCClipMask +and +.PN GCDashList +bits, respectively, in the valuemask) +cannot be requested. +Also note that an invalid resource ID (with one or more of the three +most significant bits set to 1) will be returned for +.PN GCFont , +.PN GCTile , +and +.PN GCStipple +if the component has never been explicitly set by the client. +.LP +.sp +To free a given GC, use +.PN XFreeGC . +.IN "XFreeGC" "" "@DEF@" +.sM +.FD 0 +XFreeGC\^(\^\fIdisplay\fP, \fIgc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +The +.PN XFreeGC +function destroys the specified GC as well as all the associated storage. +.LP +.PN XFreeGC +can generate a +.PN BadGC +error. +.LP +.sp +To obtain the +.PN GContext +resource ID for a given GC, use +.PN XGContextFromGC . +.IN "XGContextFromGC" "" "@DEF@" +.sM +.FD 0 +GContext XGContextFromGC\^(\^\fIgc\fP\^) +.br + GC \fIgc\fP\^; +.FN +.ds Gc for which you want the resource ID +.IP \fIgc\fP 1i +Specifies the GC \*(Gc. +.LP +.eM +.sp +Xlib usually defers sending changes to the components of a GC to the server +until a graphics function is actually called with that GC. +This permits batching of component changes into a single server request. +In some circumstances, however, it may be necessary for the client +to explicitly force sending the changes to the server. +An example might be when a protocol extension uses the GC indirectly, +in such a way that the extension interface cannot know what GC will be used. +To force sending GC component changes, use +.PN XFlushGC . +.IN "XFlushGC" "" "@DEF@" +.sM +.FD 0 +void XFlushGC\^(\^\fIdisplay\fP, \fIgc\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +.NH 2 +Using Graphics Context Convenience Routines +.XS +\*(SN Using Graphics Context Convenience Routines +.XE +.LP +This section discusses how to set the: +.IP \(bu 5 +Foreground, background, plane mask, or function components +.IP \(bu 5 +Line attributes and dashes components +.IP \(bu 5 +Fill style and fill rule components +.IP \(bu 5 +Fill tile and stipple components +.IP \(bu 5 +Font component +.IP \(bu 5 +Clip region component +.IP \(bu 5 +Arc mode, subwindow mode, and graphics exposure components +.NH 3 +Setting the Foreground, Background, Function, or Plane Mask +.XS +\*(SN Setting the Foreground, Background, Function, or Plane Mask +.XE +.LP +To set the foreground, background, plane mask, and function components +for a given GC, use +.PN XSetState . +.IN "XSetState" "" "@DEF@" +.sM +.FD 0 +XSetState\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^, \fIbackground\fP\^, \fIfunction\fP\^, \fIplane_mask\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIforeground\fP\^, \fIbackground\fP\^; +.br + int \fIfunction\fP\^; +.br + unsigned long \fIplane_mask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIforeground\fP 1i +Specifies the foreground you want to set for the specified GC. +.IP \fIbackground\fP 1i +Specifies the background you want to set for the specified GC. +.IP \fIfunction\fP 1i +Specifies the function you want to set for the specified GC. +.IP \fIplane_mask\fP 1i +Specifies the plane mask. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.LP +.eM +.PN XSetState +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the foreground of a given GC, use +.PN XSetForeground . +.IN "XSetForeground" "" "@DEF@" +.sM +.FD 0 +XSetForeground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIforeground\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIforeground\fP 1i +Specifies the foreground you want to set for the specified GC. +.LP +.eM +.PN XSetForeground +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.LP +.sp +To set the background of a given GC, use +.PN XSetBackground . +.IN "XSetBackground" "" "@DEF@" +.sM +.FD 0 +XSetBackground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIbackground\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIbackground\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIbackground\fP 1i +Specifies the background you want to set for the specified GC. +.LP +.eM +.PN XSetBackground +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.LP +.sp +To set the display function in a given GC, use +.PN XSetFunction . +.IN "XSetFunction" "" "@DEF@" +.sM +.FD 0 +XSetFunction\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfunction\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIfunction\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfunction\fP 1i +Specifies the function you want to set for the specified GC. +.LP +.eM +.PN XSetFunction +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the plane mask of a given GC, use +.PN XSetPlaneMask . +.IN "XSetPlaneMask" "" "@DEF@" +.sM +.FD 0 +XSetPlaneMask\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIplane_mask\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned long \fIplane_mask\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIplane_mask\fP 1i +Specifies the plane mask. +.\" *** JIM: NEED MORE INFO FOR THIS. *** +.LP +.eM +.PN XSetPlaneMask +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.NH 3 +Setting the Line Attributes and Dashes +.XS +\*(SN Setting the Line Attributes and Dashes +.XE +.LP +To set the line drawing components of a given GC, use +.PN XSetLineAttributes . +.IN "XSetLineAttributes" "" "@DEF@" +.sM +.FD 0 +XSetLineAttributes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIline_width\fP\^, \fIline_style\fP\^, \fIcap_style\fP\^, \fIjoin_style\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + unsigned int \fIline_width\fP\^; +.br + int \fIline_style\fP\^; +.br + int \fIcap_style\fP\^; +.br + int \fIjoin_style\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIline_width\fP 1i +Specifies the line-width you want to set for the specified GC. +.IP \fIline_style\fP 1i +Specifies the line-style you want to set for the specified GC. +You can pass +.PN LineSolid , +.PN LineOnOffDash , +or +.PN LineDoubleDash . +.IP \fIcap_style\fP 1i +Specifies the line-style and cap-style you want to set for the specified GC. +You can pass +.PN CapNotLast , +.PN CapButt , +.PN CapRound , +or +.PN CapProjecting . +.IP \fIjoin_style\fP 1i +Specifies the line join-style you want to set for the specified GC. +You can pass +.PN JoinMiter , +.PN JoinRound , +or +.PN JoinBevel . +.LP +.eM +.PN XSetLineAttributes +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the dash-offset and dash-list for dashed line styles of a given GC, use +.PN XSetDashes . +.IN "XSetDashes" "" "@DEF@" +.sM +.FD 0 +XSetDashes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIdash_offset\fP\^, \fIdash_list\fP\^, \fIn\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIdash_offset\fP\^; +.br + char \fIdash_list\fP[]\^; +.br + int \fIn\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIdash_offset\fP 1i +Specifies the phase of the pattern for the dashed line-style you want to set +for the specified GC. +.IP \fIdash_list\fP 1i +Specifies the dash-list for the dashed line-style +you want to set for the specified GC. +.IP \fIn\fP 1i +Specifies the number of elements in dash_list. +.LP +.eM +The +.PN XSetDashes +function sets the dash-offset and dash-list attributes for dashed line styles +in the specified GC. +There must be at least one element in the specified dash_list, +or a +.PN BadValue +error results. +The initial and alternating elements (second, fourth, and so on) +of the dash_list are the even dashes, and +the others are the odd dashes. +Each element specifies a dash length in pixels. +All of the elements must be nonzero, +or a +.PN BadValue +error results. +Specifying an odd-length list is equivalent to specifying the same list +concatenated with itself to produce an even-length list. +.LP +The dash-offset defines the phase of the pattern, +specifying how many pixels into the dash-list the pattern +should actually begin in any single graphics request. +Dashing is continuous through path elements combined with a join-style +but is reset to the dash-offset between each sequence of joined lines. +.LP +The unit of measure for dashes is the same for the ordinary coordinate system. +Ideally, a dash length is measured along the slope of the line, but implementations +are only required to match this ideal for horizontal and vertical lines. +Failing the ideal semantics, it is suggested that the length be measured along the +major axis of the line. +The major axis is defined as the x axis for lines drawn at an angle of between +\-45 and +45 degrees or between 135 and 225 degrees from the x axis. +For all other lines, the major axis is the y axis. +.LP +.PN XSetDashes +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.NH 3 +Setting the Fill Style and Fill Rule +.XS +\*(SN Setting the Fill Style and Fill Rule +.XE +.LP +To set the fill-style of a given GC, use +.PN XSetFillStyle . +.IN "XSetFillStyle" "" "@DEF@" +.sM +.FD 0 +XSetFillStyle\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_style\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIfill_style\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfill_style\fP 1i +Specifies the fill-style you want to set for the specified GC. +You can pass +.PN FillSolid , +.PN FillTiled , +.PN FillStippled , +or +.PN FillOpaqueStippled . +.LP +.eM +.PN XSetFillStyle +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the fill-rule of a given GC, use +.PN XSetFillRule . +.IN "XSetFillRule" "" "@DEF@" +.sM +.FD 0 +XSetFillRule\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_rule\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIfill_rule\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfill_rule\fP 1i +Specifies the fill-rule you want to set for the specified GC. +You can pass +.PN EvenOddRule +or +.PN WindingRule . +.LP +.eM +.PN XSetFillRule +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.NH 3 +Setting the Fill Tile and Stipple +.XS +\*(SN Setting the Fill Tile and Stipple +.XE +.LP +Some displays have hardware support for tiling or +stippling with patterns of specific sizes. +Tiling and stippling operations that restrict themselves to those specific +sizes run much faster than such operations with arbitrary size patterns. +Xlib provides functions that you can use to determine the best size, +tile, or stipple for the display +as well as to set the tile or stipple shape and the tile or stipple origin. +.LP +.sp +To obtain the best size of a tile, stipple, or cursor, use +.PN XQueryBestSize . +.IN "XQueryBestSize" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestSize\^(\^\fIdisplay\fP, \fIclass\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIclass\fP\^; +.br + Drawable \fIwhich_screen\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIclass\fP 1i +Specifies the class that you are interested in. +You can pass +.PN TileShape , +.PN CursorShape , +or +.PN StippleShape . +.IP \fIwhich_screen\fP 1i +Specifies any drawable on the screen. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height of the object best supported +by the display hardware. +.LP +.eM +The +.PN XQueryBestSize +function returns the best or closest size to the specified size. +For +.PN CursorShape , +this is the largest size that can be fully displayed on the screen specified by +which_screen. +For +.PN TileShape , +this is the size that can be tiled fastest. +For +.PN StippleShape , +this is the size that can be stippled fastest. +For +.PN CursorShape , +the drawable indicates the desired screen. +For +.PN TileShape +and +.PN StippleShape , +the drawable indicates the screen and possibly the window class and depth. +An +.PN InputOnly +window cannot be used as the drawable for +.PN TileShape +or +.PN StippleShape , +or a +.PN BadMatch +error results. +.LP +.PN XQueryBestSize +can generate +.PN BadDrawable , +.PN BadMatch , +and +.PN BadValue +errors. +.LP +.sp +To obtain the best fill tile shape, use +.PN XQueryBestTile . +.IN "XQueryBestTile" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestTile\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fIwhich_screen\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIwhich_screen\fP 1i +Specifies any drawable on the screen. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height of the object best supported +by the display hardware. +.LP +.eM +The +.PN XQueryBestTile +function returns the best or closest size, that is, the size that can be +tiled fastest on the screen specified by which_screen. +The drawable indicates the screen and possibly the window class and depth. +If an +.PN InputOnly +window is used as the drawable, a +.PN BadMatch +error results. +.LP +.PN XQueryBestTile +can generate +.PN BadDrawable +and +.PN BadMatch +errors. +.LP +.sp +To obtain the best stipple shape, use +.PN XQueryBestStipple . +.IN "XQueryBestStipple" "" "@DEF@" +.sM +.FD 0 +Status XQueryBestStipple\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Drawable \fIwhich_screen\fP\^; +.br + unsigned int \fIwidth\fP, \fIheight\fP\^; +.br + unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIwhich_screen\fP 1i +Specifies any drawable on the screen. +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height. +.IP \fIwidth_return\fP 1i +.br +.ns +.IP \fIheight_return\fP 1i +Return the width and height of the object best supported +by the display hardware. +.LP +.eM +The +.PN XQueryBestStipple +function returns the best or closest size, that is, the size that can be +stippled fastest on the screen specified by which_screen. +The drawable indicates the screen and possibly the window class and depth. +If an +.PN InputOnly +window is used as the drawable, a +.PN BadMatch +error results. +.LP +.PN XQueryBestStipple +can generate +.PN BadDrawable +and +.PN BadMatch +errors. +.LP +.sp +To set the fill tile of a given GC, use +.PN XSetTile . +.IN "XSetTile" "" "@DEF@" +.sM +.FD 0 +XSetTile\^(\^\fIdisplay\fP, \fIgc\fP\^, \fItile\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Pixmap \fItile\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fItile\fP 1i +Specifies the fill tile you want to set for the specified GC. +.LP +.eM +The tile and GC must have the same depth, +or a +.PN BadMatch +error results. +.LP +.PN XSetTile +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadPixmap +errors. +.LP +.sp +To set the stipple of a given GC, use +.PN XSetStipple . +.IN "XSetStipple" "" "@DEF@" +.sM +.FD 0 +XSetStipple\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIstipple\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Pixmap \fIstipple\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIstipple\fP 1i +Specifies the stipple you want to set for the specified GC. +.LP +.eM +The stipple must have a depth of one, +or a +.PN BadMatch +error results. +.LP +.PN XSetStipple +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadPixmap +errors. +.LP +.sp +To set the tile or stipple origin of a given GC, use +.PN XSetTSOrigin . +.IN "XSetTSOrigin" "" "@DEF@" +.sM +.FD 0 +XSetTSOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIts_x_origin\fP\^, \fIts_y_origin\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIts_x_origin\fP\^, \fIts_y_origin\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIts_x_origin\fP 1i +.br +.ns +.IP \fIts_y_origin\fP 1i +Specify the x and y coordinates of the tile and stipple origin. +.LP +.eM +When graphics requests call for tiling or stippling, +the parent's origin will be interpreted relative to whatever destination +drawable is specified in the graphics request. +.LP +.PN XSetTSOrigin +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.NH 3 +Setting the Current Font +.XS +\*(SN Setting the Current Font +.XE +.LP +To set the current font of a given GC, use +.PN XSetFont . +.IN "XSetFont" "" "@DEF@" +.sM +.FD 0 +XSetFont\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfont\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Font \fIfont\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIfont\fP 1i +Specifies the font. +.LP +.eM +.PN XSetFont +can generate +.PN BadAlloc , +.PN BadFont , +and +.PN BadGC +errors. +.NH 3 +Setting the Clip Region +.XS +\*(SN Setting the Clip Region +.XE +.LP +Xlib provides functions that you can use to set the clip-origin +and the clip-mask or set the clip-mask to a list of rectangles. +.LP +.sp +To set the clip-origin of a given GC, use +.PN XSetClipOrigin . +.IN "XSetClipOrigin" "" "@DEF@" +.sM +.FD 0 +XSetClipOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIclip_x_origin\fP 1i +.br +.ns +.IP \fIclip_y_origin\fP 1i +Specify the x and y coordinates of the clip-mask origin. +.LP +.eM +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in the graphics request. +.LP +.PN XSetClipOrigin +can generate +.PN BadAlloc +and +.PN BadGC +errors. +.LP +.sp +To set the clip-mask of a given GC to the specified pixmap, use +.PN XSetClipMask . +.IN "XSetClipMask" "" "@DEF@" +.sM +.FD 0 +XSetClipMask\^(\^\fIdisplay\fP, \fIgc\fP, \fIpixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Pixmap \fIpixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIpixmap\fP 1i +Specifies the pixmap or +.PN None . +.LP +.eM +If the clip-mask is set to +.PN None , +the pixels are always drawn (regardless of the clip-origin). +.LP +.PN XSetClipMask +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadPixmap +errors. +.LP +.sp +To set the clip-mask of a given GC to the specified list of rectangles, use +.PN XSetClipRectangles . +.IN "XSetClipRectangles" "" "@DEF@" +.sM +.FD 0 +XSetClipRectangles\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^, \fIrectangles\fP\^, \fIn\fP\^, \fIordering\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^; +.br + XRectangle \fIrectangles\fP[]\^; +.br + int \fIn\fP\^; +.br + int \fIordering\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIclip_x_origin\fP 1i +.br +.ns +.IP \fIclip_y_origin\fP 1i +Specify the x and y coordinates of the clip-mask origin. +.IP \fIrectangles\fP 1i +Specifies an array of rectangles that define the clip-mask. +.IP \fIn\fP 1i +Specifies the number of rectangles. +.IP \fIordering\fP 1i +Specifies the ordering relations on the rectangles. +You can pass +.PN Unsorted , +.PN YSorted , +.PN YXSorted , +or +.PN YXBanded . +.LP +.eM +The +.PN XSetClipRectangles +function changes the clip-mask in the specified GC +to the specified list of rectangles and sets the clip origin. +The output is clipped to remain contained within the +rectangles. +The clip-origin is interpreted relative to the origin of +whatever destination drawable is specified in a graphics request. +The rectangle coordinates are interpreted relative to the clip-origin. +The rectangles should be nonintersecting, or the graphics results will be +undefined. +Note that the list of rectangles can be empty, +which effectively disables output. +This is the opposite of passing +.PN None +as the clip-mask in +.PN XCreateGC , +.PN XChangeGC , +and +.PN XSetClipMask . +.LP +If known by the client, ordering relations on the rectangles can be +specified with the ordering argument. +This may provide faster operation +by the server. +If an incorrect ordering is specified, the X server may generate a +.PN BadMatch +error, but it is not required to do so. +If no error is generated, the graphics +results are undefined. +.PN Unsorted +means the rectangles are in arbitrary order. +.PN YSorted +means that the rectangles are nondecreasing in their Y origin. +.PN YXSorted +additionally constrains +.PN YSorted +order in that all +rectangles with an equal Y origin are nondecreasing in their X +origin. +.PN YXBanded +additionally constrains +.PN YXSorted +by requiring that, +for every possible Y scanline, all rectangles that include that +scanline have an identical Y origins and Y extents. +.LP +.PN XSetClipRectangles +can generate +.PN BadAlloc , +.PN BadGC , +.PN BadMatch , +and +.PN BadValue +errors. +.LP +Xlib provides a set of basic functions for performing +region arithmetic. +For information about these functions, +see section 16.5. +.NH 3 +Setting the Arc Mode, Subwindow Mode, and Graphics Exposure +.XS +\*(SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure +.XE +.LP +To set the arc mode of a given GC, use +.PN XSetArcMode . +.IN "XSetArcMode" "" "@DEF@" +.sM +.FD 0 +XSetArcMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIarc_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIarc_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIarc_mode\fP 1i +Specifies the arc mode. +You can pass +.PN ArcChord +or +.PN ArcPieSlice . +.LP +.eM +.PN XSetArcMode +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the subwindow mode of a given GC, use +.PN XSetSubwindowMode . +.IN "XSetSubwindowMode" "" "@DEF@" +.sM +.FD 0 +XSetSubwindowMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIsubwindow_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + int \fIsubwindow_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIsubwindow_mode\fP 1i +Specifies the subwindow mode. +You can pass +.PN ClipByChildren +or +.PN IncludeInferiors . +.LP +.eM +.PN XSetSubwindowMode +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.LP +.sp +To set the graphics-exposures flag of a given GC, use +.PN XSetGraphicsExposures . +.IN "XSetGraphicsExposures" "" "@DEF@" +.sM +.FD 0 +XSetGraphicsExposures\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIgraphics_exposures\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.br + Bool \fIgraphics_exposures\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.IP \fIgraphics_exposures\fP 1i +Specifies a Boolean value that indicates whether you want +.PN GraphicsExpose +and +.PN NoExpose +events to be reported when calling +.PN XCopyArea +and +.PN XCopyPlane +with this GC. +.LP +.eM +.PN XSetGraphicsExposures +can generate +.PN BadAlloc , +.PN BadGC , +and +.PN BadValue +errors. +.bp |