2 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
4 .\" Permission is hereby granted, free of charge, to any person obtaining
5 .\" a copy of this software and associated documentation files (the
6 .\" "Software"), to deal in the Software without restriction, including
7 .\" without limitation the rights to use, copy, modify, merge, publish,
8 .\" distribute, sublicense, and/or sell copies of the Software, and to
9 .\" permit persons to whom the Software is furnished to do so, subject to
10 .\" the following conditions:
12 .\" The above copyright notice and this permission notice shall be included
13 .\" in all copies or substantial portions of the Software.
15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
19 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
20 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
21 .\" OTHER DEALINGS IN THE SOFTWARE.
23 .\" Except as contained in this notice, the name of the X Consortium shall
24 .\" not be used in advertising or otherwise to promote the sale, use or
25 .\" other dealings in this Software without prior written authorization
26 .\" from the X Consortium.
28 .\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
29 .\" Digital Equipment Corporation
31 .\" Portions Copyright \(co 1990, 1991 by
34 .\" Permission to use, copy, modify and distribute this documentation for
35 .\" any purpose and without fee is hereby granted, provided that the above
36 .\" copyright notice appears in all copies and that both that copyright notice
37 .\" and this permission notice appear in all copies, and that the names of
38 .\" Digital and Tektronix not be used in in advertising or publicity pertaining
39 .\" to this documentation without specific, written prior permission.
40 .\" Digital and Tektronix makes no representations about the suitability
41 .\" of this documentation for any purpose.
42 .\" It is provided ``as is'' without express or implied warranty.
45 .ds xT X Toolkit Intrinsics \- C Language Interface
46 .ds xW Athena X Widgets \- C Language X Toolkit Interface
47 .ds xL Xlib \- C Language X Interface
48 .ds xC Inter-Client Communication Conventions Manual
55 .\".if \\n(VS>=40 .vs \\n(VSu
56 .\".if \\n(VS<=39 .vs \\n(VSp
67 .de IN \" send an index entry to the stderr
70 .ie t \\$1\fB\^\\$2\^\fR\\$3
71 .el \\$1\fI\^\\$2\^\fP\\$3
74 .ie t \fB\^\\$1\^\fR\\$2
75 .el \fI\^\\$1\^\fP\\$2
78 .ie t <\fB\\$1\fR>\\$2
83 .TH XCreateGC __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
85 XCreateGC, XCopyGC, XChangeGC, XGetGCValues, XFreeGC, XGContextFromGC, XGCValues \- create or free graphics contexts and graphics context structure
88 GC XCreateGC\^(\^Display *\fIdisplay\fP\^, Drawable \fId\fP\^, unsigned long
89 \fIvaluemask\fP\^, XGCValues *\^\fIvalues\fP\^);
91 int XCopyGC\^(\^Display *\fIdisplay\fP\^, GC \fIsrc\fP\^,
92 unsigned long \fIvaluemask\fP\^, GC \fIdest\fP\^);
94 int XChangeGC\^(\^Display *\fIdisplay\fP\^, GC \fIgc\fP\^, unsigned long
95 \fIvaluemask\fP\^, XGCValues *\^\fIvalues\fP\^);
97 Status XGetGCValues\^(\^Display *\fIdisplay\fP\^, GC \fIgc\fP\^, unsigned long
98 \fIvaluemask\fP\^, XGCValues *\fIvalues_return\fP\^);
100 int XFreeGC\^(\^Display *\fIdisplay\fP\^, GC \fIgc\fP\^);
102 GContext XGContextFromGC\^(\^GC \fIgc\fP\^);
105 Specifies the drawable.
107 Specifies the destination GC.
109 Specifies the connection to the X server.
113 Specifies the components of the source GC.
114 .ds Vm set, copied, changed, or returned
115 .IP \fIvaluemask\fP 1i
116 Specifies which components in the GC are to be \*(Vm.
117 This argument is the bitwise inclusive OR of zero or more of the valid
118 GC component mask bits.
120 Specifies any values as specified by the valuemask.
121 .IP \fIvalues_return\fP 1i
122 Returns the GC values in the specified
128 function creates a graphics context and returns a GC.
129 The GC can be used with any destination drawable having the same root
130 and depth as the specified drawable.
131 Use with other drawables results in a
148 function copies the specified components from the source GC
149 to the destination GC.
150 The source and destination GCs must have the same root and depth,
154 The valuemask specifies which component to copy, as for
167 function changes the components specified by valuemask for
169 The values argument contains the values to be set.
170 The values and restrictions are the same as for
172 Changing the clip-mask overrides any previous
173 .ZN XSetClipRectangles
174 request on the context.
175 Changing the dash-offset or dash-list
176 overrides any previous
178 request on the context.
179 The order in which components are verified and altered is server dependent.
180 If an error is generated, a subset of the components may have been altered.
195 function returns the components specified by valuemask for the specified GC.
196 If the valuemask contains a valid set of GC mask bits
209 .ZN GCTileStipXOrigin ,
210 .ZN GCTileStipYOrigin ,
212 .ZN GCSubwindowMode ,
213 .ZN GCGraphicsExposures ,
221 sets the requested components in values_return and returns a nonzero status.
222 Otherwise, it returns a zero status.
223 Note that the clip-mask and dash-list (represented by the
227 bits, respectively, in the valuemask)
229 Also note that an invalid resource ID (with one or more of the three
230 most significant bits set to 1) will be returned for
235 if the component has never been explicitly set by the client.
239 function destroys the specified GC as well as all the associated storage.
251 /\&* GC attribute value mask bits */
253 lw(.5i) lw(2.5i) lw(.75i).
341 .ZN GCTileStipXOrigin
348 .ZN GCTileStipYOrigin
369 .ZN GCGraphicsExposures
416 .IN "XGCValues" "" "@DEF@"
421 int function; /\&* logical operation */
422 unsigned long plane_mask; /\&* plane mask */
423 unsigned long foreground; /\&* foreground pixel */
424 unsigned long background; /\&* background pixel */
425 int line_width; /\&* line width (in pixels) */
426 int line_style; /\&* LineSolid, LineOnOffDash, LineDoubleDash */
427 int cap_style; /\&* CapNotLast, CapButt, CapRound, CapProjecting */
428 int join_style; /\&* JoinMiter, JoinRound, JoinBevel */
429 int fill_style; /\&* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
430 int fill_rule; /\&* EvenOddRule, WindingRule */
431 int arc_mode; /\&* ArcChord, ArcPieSlice */
432 Pixmap tile; /\&* tile pixmap for tiling operations */
433 Pixmap stipple; /\&* stipple 1 plane pixmap for stippling */
434 int ts_x_origin; /\&* offset for tile or stipple operations */
436 Font font; /\&* default text font for text operations */
437 int subwindow_mode; /\&* ClipByChildren, IncludeInferiors */
438 Bool graphics_exposures; /\&* boolean, should exposures be generated */
439 int clip_x_origin; /\&* origin for clipping */
441 Pixmap clip_mask; /\&* bitmap clipping; other calls for rects */
442 int dash_offset; /\&* patterned/dashed line information */
447 The function attributes of a GC are used when you update a section of
448 a drawable (the destination) with bits from somewhere else (the source).
449 The function in a GC defines how the new destination bits are to be
450 computed from the source bits and the old destination bits.
452 is typically the most useful because it will work on a color display,
453 but special applications may use other functions,
454 particularly in concert with particular planes of a color display.
455 The 16 GC functions, defined in
458 .\" are listed in Table 5-1 along with the
459 .\"the associated hexadecimal code
464 lw(1.5i) cw(.5i) lw(2i).
468 Function Name Value Operation
533 (NOT src) AND (NOT dst)
575 (NOT src) OR (NOT dst)
588 Many graphics operations depend on either pixel values or planes in a GC.
590 The planes attribute is of type long, and it specifies which planes of the
591 destination are to be modified, one bit per plane.
593 A monochrome display has only one plane and
594 will be the least significant bit of the word.
595 As planes are added to the display hardware, they will occupy more
596 significant bits in the plane mask.
598 In graphics operations, given a source and destination pixel,
599 the result is computed bitwise on corresponding bits of the pixels.
600 That is, a Boolean operation is performed in each bit plane.
601 The plane_mask restricts the operation to a subset of planes.
604 can be used to refer to all planes of the screen simultaneously.
605 The result is computed by the following:
608 ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
611 Range checking is not performed on the values for foreground,
612 background, or plane_mask.
613 They are simply truncated to the appropriate
615 The line-width is measured in pixels and either can be greater than or equal to
616 one (wide line) or can be the special value zero (thin line).
618 Wide lines are drawn centered on the path described by the graphics request.
619 Unless otherwise specified by the join-style or cap-style,
620 the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
621 width w is a rectangle with vertices at the following real coordinates:
624 [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
625 [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
628 Here sn is the sine of the angle of the line,
629 and cs is the cosine of the angle of the line.
630 A pixel is part of the line and so is drawn
631 if the center of the pixel is fully inside the bounding box
632 (which is viewed as having infinitely thin edges).
633 If the center of the pixel is exactly on the bounding box,
634 it is part of the line if and only if the interior is immediately to its right
635 (x increasing direction).
636 Pixels with centers on a horizontal edge are a special case and are part of
637 the line if and only if the interior or the boundary is immediately below
638 (y increasing direction) and the interior or the boundary is immediately
639 to the right (x increasing direction).
641 Thin lines (zero line-width) are one-pixel-wide lines drawn using an
642 unspecified, device-dependent algorithm.
643 There are only two constraints on this algorithm.
645 If a line is drawn unclipped from [x1,y1] to [x2,y2] and
646 if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
647 a point [x,y] is touched by drawing the first line
648 if and only if the point [x+dx,y+dy] is touched by drawing the second line.
650 The effective set of points comprising a line cannot be affected by clipping.
651 That is, a point is touched in a clipped line if and only if the point
652 lies inside the clipping region and the point would be touched
653 by the line when drawn unclipped.
655 A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
656 as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
658 It is recommended that this property be true for thin lines,
659 but this is not required.
660 A line-width of zero may differ from a line-width of one in which pixels are
662 This permits the use of many manufacturers' line drawing hardware,
663 which may run many times faster than the more precisely specified
667 drawing a thin line will be faster than drawing a wide line of width one.
668 However, because of their different drawing algorithms,
669 thin lines may not mix well aesthetically with wide lines.
670 If it is desirable to obtain precise and uniform results across all displays,
671 a client should always use a line-width of one rather than a line-width of zero.
673 The line-style defines which sections of a line are drawn:
679 The full path of the line is drawn.
685 The full path of the line is drawn,
686 but the even dashes are filled differently
687 from the odd dashes (see fill-style) with
689 style used where even and odd dashes meet.
695 Only the even dashes are drawn,
696 and cap-style applies to
697 all internal ends of the individual dashes,
705 The cap-style defines how the endpoints of a path are drawn:
706 .IN "Graphics context" "path"
712 This is equivalent to
714 except that for a line-width of zero the final endpoint is not drawn.
720 The line is square at the endpoint (perpendicular to the slope of the line)
721 with no projection beyond.
727 The line has a circular arc with the diameter equal to the line-width,
728 centered on the endpoint.
729 (This is equivalent to
731 for line-width of zero).
737 The line is square at the end, but the path continues beyond the endpoint
738 for a distance equal to half the line-width.
739 (This is equivalent to
741 for line-width of zero).
745 The join-style defines how corners are drawn for wide lines:
751 The outer edges of two lines extend to meet at an angle.
752 However, if the angle is less than 11 degrees,
755 join-style is used instead.
761 The corner is a circular arc with the diameter equal to the line-width,
762 centered on the joinpoint.
770 endpoint styles with the triangular notch filled.
774 For a line with coincident endpoints (x1=x2, y1=y2),
775 when the cap-style is applied to both endpoints,
776 the semantics depends on the line-width and the cap-style:
778 lw(1.3i) lw(.5i) lw(4i).
784 The results are device dependent,
785 but the desired effect is that nothing is drawn.
793 The results are device dependent,
794 but the desired effect is that a single pixel is drawn.
802 The results are the same as for
811 The results are the same as for
828 The closed path is a circle, centered at the endpoint, and
829 with the diameter equal to the line-width.
837 The closed path is a square, aligned with the coordinate axes, centered at the
838 endpoint, and with the sides equal to the line-width.
842 For a line with coincident endpoints (x1=x2, y1=y2),
843 when the join-style is applied at one or both endpoints,
844 the effect is as if the line was removed from the overall path.
845 However, if the total path consists of or is reduced to a single point joined
846 with itself, the effect is the same as when the cap-style is applied at both
849 The tile/stipple represents an infinite two-dimensional plane,
850 with the tile/stipple replicated in all dimensions.
851 When that plane is superimposed on the drawable
852 for use in a graphics operation, the upper-left corner
853 of some instance of the tile/stipple is at the coordinates within
854 the drawable specified by the tile/stipple origin.
855 The tile/stipple and clip origins are interpreted relative to the
856 origin of whatever destination drawable is specified in a graphics
858 The tile pixmap must have the same root and depth as the GC,
862 The stipple pixmap must have depth one and must have the same root as the
866 For stipple operations where the fill-style is
869 .ZN FillOpaqueStippled ,
870 the stipple pattern is tiled in a
871 single plane and acts as an additional clip mask to be ANDed with the clip-mask.
872 Although some sizes may be faster to use than others,
873 any size pixmap can be used for tiling or stippling.
875 The fill-style defines the contents of the source for line, text, and
877 For all text and fill requests (for example,
892 and for the even dashes for line requests with line-style
912 .ZN FillOpaqueStippled
914 A tile with the same width and height as stipple,
915 but with background everywhere stipple has a zero
916 and with foreground everywhere stipple has a one
922 Foreground masked by stipple
926 When drawing lines with line-style
928 the odd dashes are controlled by the fill-style in the following manner:
940 Same as for even dashes
944 .ZN FillOpaqueStippled
946 Same as for even dashes
952 Background masked by stipple
956 Storing a pixmap in a GC might or might not result in a copy
958 If the pixmap is later used as the destination for a graphics request,
959 the change might or might not be reflected in the GC.
960 If the pixmap is used simultaneously in a graphics request both as
961 a destination and as a tile or stipple,
962 the results are undefined.
964 For optimum performance,
965 you should draw as much as possible with the same GC
966 (without changing its components).
967 The costs of changing GC components relative to using different GCs
968 depend on the display hardware and the server implementation.
969 It is quite likely that some amount of GC information will be
970 cached in display hardware and that such hardware can only cache a small number
973 The dashes value is actually a simplified form of the
974 more general patterns that can be set with
977 value of N is equivalent to specifying the two-element list [N, N] in
979 The value must be nonzero,
984 The clip-mask restricts writes to the destination drawable.
985 If the clip-mask is set to a pixmap,
986 it must have depth one and have the same root as the GC,
990 If clip-mask is set to
992 the pixels are always drawn regardless of the clip origin.
993 The clip-mask also can be set by calling the
994 .ZN XSetClipRectangles
998 Only pixels where the clip-mask has a bit set to 1 are drawn.
999 Pixels are not drawn outside the area covered by the clip-mask
1000 or where the clip-mask has a bit set to 0.
1001 The clip-mask affects all graphics requests.
1002 The clip-mask does not clip sources.
1003 The clip-mask origin is interpreted relative to the origin of whatever
1004 destination drawable is specified in a graphics request.
1006 You can set the subwindow-mode to
1009 .ZN IncludeInferiors .
1011 .ZN ClipByChildren ,
1012 both source and destination windows are
1013 additionally clipped by all viewable
1017 .ZN IncludeInferiors ,
1018 neither source nor destination window is clipped by inferiors.
1019 This will result in including subwindow contents in the source
1020 and drawing through subwindow boundaries of the destination.
1022 .ZN IncludeInferiors
1023 on a window of one depth with mapped
1024 inferiors of differing depth is not illegal, but the semantics are
1025 undefined by the core protocol.
1027 The fill-rule defines what pixels are inside (drawn) for
1030 requests and can be set to
1036 a point is inside if
1037 an infinite ray with the point as origin crosses the path an odd number
1041 a point is inside if an infinite ray with the
1042 point as origin crosses an unequal number of clockwise and
1043 counterclockwise directed path segments.
1044 A clockwise directed path segment is one that crosses the ray from left to
1045 right as observed from the point.
1046 A counterclockwise segment is one that crosses the ray from right to left
1047 as observed from the point.
1048 The case where a directed line segment is coincident with the ray is
1049 uninteresting because you can simply choose a different ray that is not
1050 coincident with a segment.
1056 a point is infinitely small,
1057 and the path is an infinitely thin line.
1058 A pixel is inside if the center point of the pixel is inside
1059 and the center point is not on the boundary.
1060 If the center point is on the boundary,
1061 the pixel is inside if and only if the polygon interior is immediately to
1062 its right (x increasing direction).
1063 Pixels with centers on a horizontal edge are a special case
1064 and are inside if and only if the polygon interior is immediately below
1065 (y increasing direction).
1067 The arc-mode controls filling in the
1069 function and can be set to
1075 the arcs are pie-slice filled.
1078 the arcs are chord filled.
1080 The graphics-exposure flag controls
1087 requests (and any similar requests defined by extensions).
1091 The server failed to allocate the requested resource or server memory.
1094 A value for a Drawable argument does not name a defined Window or Pixmap.
1097 A value for a Font or GContext argument does not name a defined Font.
1100 A value for a GContext argument does not name a defined GContext.
1105 window is used as a Drawable.
1108 Some argument or pair of arguments has the correct type and range but fails
1109 to match in some other way required by the request.
1112 A value for a Pixmap argument does not name a defined Pixmap.
1115 Some numeric value falls outside the range of values accepted by the request.
1116 Unless a specific range is specified for an argument, the full range defined
1117 by the argument's type is accepted. Any argument defined as a set of
1118 alternatives can generate this error.
1120 AllPlanes(__libmansuffix__),
1121 XCopyArea(__libmansuffix__),
1122 XCreateRegion(__libmansuffix__),
1123 XDrawArc(__libmansuffix__),
1124 XDrawLine(__libmansuffix__),
1125 XDrawRectangle(__libmansuffix__),
1126 XDrawText(__libmansuffix__),
1127 XFillRectangle(__libmansuffix__),
1128 XQueryBestSize(__libmansuffix__),
1129 XSetArcMode(__libmansuffix__),
1130 XSetClipOrigin(__libmansuffix__),
1131 XSetFillStyle(__libmansuffix__),
1132 XSetFont(__libmansuffix__),
1133 XSetLineAttributes(__libmansuffix__),
1134 XSetState(__libmansuffix__),
1135 XSetTile(__libmansuffix__)
projects / platform / upstream / libX11.git / blob