1XCreateGC(3)                    XLIB FUNCTIONS                    XCreateGC(3)
2
3
4

NAME

6       XCreateGC, XCopyGC, XChangeGC, XGetGCValues, XFreeGC, XGContextFromGC,
7       XGCValues - create or free graphics contexts and graphics context
8       structure
9

SYNTAX

11       GC XCreateGC(Display *display, Drawable d, unsigned long valuemask,
12              XGCValues *values);
13
14       int XCopyGC(Display *display, GC src, unsigned long valuemask, GC
15              dest);
16
17       int XChangeGC(Display *display, GC gc, unsigned long valuemask, XGCVal‐
18              ues *values);
19
20       Status XGetGCValues(Display *display, GC gc, unsigned long valuemask,
21              XGCValues *values_return);
22
23       int XFreeGC(Display *display, GC gc);
24
25       GContext XGContextFromGC(GC gc);
26

ARGUMENTS

28       d         Specifies the drawable.
29
30       dest      Specifies the destination GC.
31
32       display   Specifies the connection to the X server.
33
34       gc        Specifies the GC.
35
36       src       Specifies the components of the source GC.
37
38       valuemask Specifies which components in the GC are to be set, copied,
39                 changed, or returned .  This argument is the bitwise inclu‐
40                 sive OR of zero or more of the valid GC component mask bits.
41
42       values    Specifies any values as specified by the valuemask.
43
44       values_return
45                 Returns the GC values in the specified XGCValues structure.
46

DESCRIPTION

48       The XCreateGC function creates a graphics context and returns a GC.
49       The GC can be used with any destination drawable having the same root
50       and depth as the specified drawable.  Use with other drawables results
51       in a BadMatch error.
52
53       XCreateGC can generate BadAlloc, BadDrawable, BadFont, BadMatch, Bad‐
54       Pixmap, and BadValue errors.
55
56       The XCopyGC function copies the specified components from the source GC
57       to the destination GC.  The source and destination GCs must have the
58       same root and depth, or a BadMatch error results.  The valuemask speci‐
59       fies which component to copy, as for XCreateGC.
60
61       XCopyGC can generate BadAlloc, BadGC, and BadMatch errors.
62
63       The XChangeGC function changes the components specified by valuemask
64       for the specified GC.  The values argument contains the values to be
65       set.  The values and restrictions are the same as for XCreateGC.
66       Changing the clip-mask overrides any previous XSetClipRectangles
67       request on the context.  Changing the dash-offset or dash-list over‐
68       rides any previous XSetDashes request on the context.  The order in
69       which components are verified and altered is server dependent.  If an
70       error is generated, a subset of the components may have been altered.
71
72       XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch, BadPixmap,
73       and BadValue errors.
74
75       The XGetGCValues function returns the components specified by valuemask
76       for the specified GC.  If the valuemask contains a valid set of GC mask
77       bits (GCFunction, GCPlaneMask, GCForeground, GCBackground, GCLineWidth,
78       GCLineStyle, GCCapStyle, GCJoinStyle, GCFillStyle, GCFillRule, GCTile,
79       GCStipple, GCTileStipXOrigin, GCTileStipYOrigin, GCFont, GCSubwindow‐
80       Mode, GCGraphicsExposures, GCClipXOrigin, GCCLipYOrigin, GCDashOffset,
81       or GCArcMode) and no error occurs, XGetGCValues sets the requested com‐
82       ponents in values_return and returns a nonzero status.  Otherwise, it
83       returns a zero status.  Note that the clip-mask and dash-list (repre‐
84       sented by the GCClipMask and GCDashList bits, respectively, in the val‐
85       uemask) cannot be requested.  Also note that an invalid resource ID
86       (with one or more of the three most significant bits set to 1) will be
87       returned for GCFont, GCTile, and GCStipple if the component has never
88       been explicitly set by the client.
89
90       The XFreeGC function destroys the specified GC as well as all the asso‐
91       ciated storage.
92
93       XFreeGC can generate a BadGC error.
94

STRUCTURES

96       The XGCValues structure contains:
97
98       /* GC attribute value mask bits */
99
100       #define   GCFunction                  (1L<<0)
101       #define   GCPlaneMask                 (1L<<1)
102       #define   GCForeground                (1L<<2)
103       #define   GCBackground                (1L<<3)
104       #define   GCLineWidth                 (1L<<4)
105       #define   GCLineStyle                 (1L<<5)
106       #define   GCCapStyle                  (1L<<6)
107       #define   GCJoinStyle                 (1L<<7)
108       #define   GCFillStyle                 (1L<<8)
109       #define   GCFillRule                  (1L<<9)
110       #define   GCTile                      (1L<<10)
111       #define   GCStipple                   (1L<<11)
112       #define   GCTileStipXOrigin           (1L<<12)
113       #define   GCTileStipYOrigin           (1L<<13)
114       #define   GCFont                      (1L<<14)
115       #define   GCSubwindowMode             (1L<<15)
116       #define   GCGraphicsExposures         (1L<<16)
117       #define   GCClipXOrigin               (1L<<17)
118       #define   GCClipYOrigin               (1L<<18)
119       #define   GCClipMask                  (1L<<19)
120       #define   GCDashOffset                (1L<<20)
121       #define   GCDashList                  (1L<<21)
122       #define   GCArcMode                   (1L<<22)
123
124       /* Values */
125
126       typedef struct {
127               int function;   /* logical operation */
128               unsigned long plane_mask;       /* plane mask */
129               unsigned long foreground;       /* foreground pixel */
130               unsigned long background;       /* background pixel */
131               int line_width; /* line width (in pixels) */
132               int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */
133               int cap_style;  /* CapNotLast, CapButt, CapRound, CapProjecting */
134               int join_style; /* JoinMiter, JoinRound, JoinBevel */
135               int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
136               int fill_rule;  /* EvenOddRule, WindingRule */
137               int arc_mode;   /* ArcChord, ArcPieSlice */
138               Pixmap tile;    /* tile pixmap for tiling operations */
139               Pixmap stipple; /* stipple 1 plane pixmap for stippling */
140               int ts_x_origin;        /* offset for tile or stipple operations */
141               int ts_y_origin;
142               Font font;      /* default text font for text operations */
143               int subwindow_mode;     /* ClipByChildren, IncludeInferiors */
144               Bool graphics_exposures;        /* boolean, should exposures be generated */
145               int clip_x_origin;      /* origin for clipping */
146               int clip_y_origin;
147               Pixmap clip_mask;       /* bitmap clipping; other calls for rects */
148               int dash_offset;        /* patterned/dashed line information */
149               char dashes;
150       } XGCValues;
151
152       The function attributes of a GC are used when you update a section of a
153       drawable (the destination) with bits from somewhere else (the source).
154       The function in a GC defines how the new destination bits are to be
155       computed from the source bits and the old destination bits.  GXcopy is
156       typically the most useful because it will work on a color display, but
157       special applications may use other functions, particularly in concert
158       with particular planes of a color display.  The 16 GC functions,
159       defined in <X11/X.h>, are:
160
161       ───────────────────────────────────────────────
162       Function Name     Value   Operation
163       ───────────────────────────────────────────────
164       GXclear            0x0    0
165       GXand              0x1    src AND dst
166       GXandReverse       0x2    src AND NOT dst
167       GXcopy             0x3    src
168       GXandInverted      0x4    (NOT src) AND dst
169       GXnoop             0x5    dst
170       GXxor              0x6    src XOR dst
171       GXor               0x7    src OR dst
172       GXnor              0x8    (NOT src) AND (NOT
173                                 dst)
174       GXequiv            0x9    (NOT src) XOR dst
175       GXinvert           0xa    NOT dst
176       GXorReverse        0xb    src OR (NOT dst)
177       GXcopyInverted     0xc    NOT src
178       GXorInverted       0xd    (NOT src) OR dst
179       GXnand             0xe    (NOT src) OR (NOT
180                                 dst)
181       GXset              0xf    1
182       ───────────────────────────────────────────────
183
184       Many graphics operations depend on either pixel values or planes in a
185       GC.  The planes attribute is of type long, and it specifies which
186       planes of the destination are to be modified, one bit per plane.  A
187       monochrome display has only one plane and will be the least significant
188       bit of the word.  As planes are added to the display hardware, they
189       will occupy more significant bits in the plane mask.
190
191       In graphics operations, given a source and destination pixel, the
192       result is computed bitwise on corresponding bits of the pixels.  That
193       is, a Boolean operation is performed in each bit plane.  The plane_mask
194       restricts the operation to a subset of planes.  A macro constant
195       AllPlanes can be used to refer to all planes of the screen simultane‐
196       ously.  The result is computed by the following:
197
198       ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
199
200       Range checking is not performed on the values for foreground, back‐
201       ground, or plane_mask.  They are simply truncated to the appropriate
202       number of bits.  The line-width is measured in pixels and either can be
203       greater than or equal to one (wide line) or can be the special value
204       zero (thin line).
205
206       Wide lines are drawn centered on the path described by the graphics
207       request.  Unless otherwise specified by the join-style or cap-style,
208       the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
209       width w is a rectangle with vertices at the following real coordinates:
210
211       [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
212       [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
213
214       Here sn is the sine of the angle of the line, and cs is the cosine of
215       the angle of the line.  A pixel is part of the line and so is drawn if
216       the center of the pixel is fully inside the bounding box (which is
217       viewed as having infinitely thin edges).  If the center of the pixel is
218       exactly on the bounding box, it is part of the line if and only if the
219       interior is immediately to its right (x increasing direction).  Pixels
220       with centers on a horizontal edge are a special case and are part of
221       the line if and only if the interior or the boundary is immediately
222       below (y increasing direction) and the interior or the boundary is
223       immediately to the right (x increasing direction).
224
225       Thin lines (zero line-width) are one-pixel-wide lines drawn using an
226       unspecified, device-dependent algorithm.  There are only two con‐
227       straints on this algorithm.
228
229       1.   If a line is drawn unclipped from [x1,y1] to [x2,y2] and if
230            another line is drawn unclipped from [x1+dx,y1+dy] to
231            [x2+dx,y2+dy], a point [x,y] is touched by drawing the first line
232            if and only if the point [x+dx,y+dy] is touched by drawing the
233            second line.
234
235       2.   The effective set of points comprising a line cannot be affected
236            by clipping.  That is, a point is touched in a clipped line if and
237            only if the point lies inside the clipping region and the point
238            would be touched by the line when drawn unclipped.
239
240       A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels
241       as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style
242       and join-style.  It is recommended that this property be true for thin
243       lines, but this is not required.  A line-width of zero may differ from
244       a line-width of one in which pixels are drawn.  This permits the use of
245       many manufacturers' line drawing hardware, which may run many times
246       faster than the more precisely specified wide lines.
247
248       In general, drawing a thin line will be faster than drawing a wide line
249       of width one.  However, because of their different drawing algorithms,
250       thin lines may not mix well aesthetically with wide lines.  If it is
251       desirable to obtain precise and uniform results across all displays, a
252       client should always use a line-width of one rather than a line-width
253       of zero.
254
255       The line-style defines which sections of a line are drawn:
256
257       LineSolid       The full path of the line is drawn.
258       LineDou‐        The full path of the line is drawn, but the
259       bleDash         even dashes are filled differently from the
260                       odd dashes (see fill-style) with CapButt
261                       style used where even and odd dashes meet.
262
263
264
265       LineOnOffDash   Only the even dashes are drawn, and cap-style
266                       applies to all internal ends of the individ‐
267                       ual dashes, except CapNotLast is treated as
268                       CapButt.
269
270       The cap-style defines how the endpoints of a path are drawn:
271
272       CapNotLast      This is equivalent to CapButt except that for
273                       a line-width of zero the final endpoint is
274                       not drawn.
275       CapButt         The line is square at the endpoint (perpen‐
276                       dicular to the slope of the line) with no
277                       projection beyond.
278       CapRound        The line has a circular arc with the diameter
279                       equal to the line-width, centered on the end‐
280                       point.  (This is equivalent to CapButt for
281                       line-width of zero).
282       CapProjecting   The line is square at the end, but the path
283                       continues beyond the endpoint for a distance
284                       equal to half the line-width.  (This is
285                       equivalent to CapButt for line-width of
286                       zero).
287
288       The join-style defines how corners are drawn for wide lines:
289
290       JoinMiter       The outer edges of two lines extend to meet
291                       at an angle.  However, if the angle is less
292                       than 11 degrees, then a JoinBevel join-style
293                       is used instead.
294       JoinRound       The corner is a circular arc with the diame‐
295                       ter equal to the line-width, centered on the
296                       joinpoint.
297       JoinBevel       The corner has CapButt endpoint styles with
298                       the triangular notch filled.
299
300       For a line with coincident endpoints (x1=x2, y1=y2), when the cap-style
301       is applied to both endpoints, the semantics depends on the line-width
302       and the cap-style:
303
304       CapNotLast      thin    The results are device dependent, but
305                               the desired effect is that nothing is
306                               drawn.
307       CapButt         thin    The results are device dependent, but
308                               the desired effect is that a single
309                               pixel is drawn.
310       CapRound        thin    The results are the same as for Cap‐
311                               Butt/thin.
312       CapProjecting   thin    The results are the same as for Cap‐
313                               Butt/thin.
314       CapButt         wide    Nothing is drawn.
315       CapRound        wide    The closed path is a circle, centered at
316                               the endpoint, and with the diameter
317                               equal to the line-width.
318       CapProjecting   wide    The closed path is a square, aligned
319                               with the coordinate axes, centered at
320                               the endpoint, and with the sides equal
321                               to the line-width.
322
323       For a line with coincident endpoints (x1=x2, y1=y2), when the join-
324       style is applied at one or both endpoints, the effect is as if the line
325       was removed from the overall path.  However, if the total path consists
326       of or is reduced to a single point joined with itself, the effect is
327       the same as when the cap-style is applied at both endpoints.
328
329       The tile/stipple represents an infinite two-dimensional plane, with the
330       tile/stipple replicated in all dimensions.  When that plane is superim‐
331       posed on the drawable for use in a graphics operation, the upper-left
332       corner of some instance of the tile/stipple is at the coordinates
333       within the drawable specified by the tile/stipple origin.  The
334       tile/stipple and clip origins are interpreted relative to the origin of
335       whatever destination drawable is specified in a graphics request.  The
336       tile pixmap must have the same root and depth as the GC, or a BadMatch
337       error results.  The stipple pixmap must have depth one and must have
338       the same root as the GC, or a BadMatch error results.  For stipple
339       operations where the fill-style is FillStippled but not FillOpaqueStip‐
340       pled, the stipple pattern is tiled in a single plane and acts as an
341       additional clip mask to be ANDed with the clip-mask.  Although some
342       sizes may be faster to use than others, any size pixmap can be used for
343       tiling or stippling.
344
345       The fill-style defines the contents of the source for line, text, and
346       fill requests.  For all text and fill requests (for example, XDrawText,
347       XDrawText16, XFillRectangle, XFillPolygon, and XFillArc); for line
348       requests with line-style LineSolid (for example, XDrawLine, XDrawSeg‐
349       ments, XDrawRectangle, XDrawArc); and for the even dashes for line
350       requests with line-style LineOnOffDash or LineDoubleDash, the following
351       apply:
352
353       FillSolid            Foreground
354       FillTiled            Tile
355       FillOpaqueStippled   A tile with the same width and height as
356                            stipple, but with background everywhere
357                            stipple has a zero and with foreground
358                            everywhere stipple has a one
359       FillStippled         Foreground masked by stipple
360
361       When drawing lines with line-style LineDoubleDash, the odd dashes are
362       controlled by the fill-style in the following manner:
363
364       FillSolid            Background
365       FillTiled            Same as for even dashes
366       FillOpaqueStippled   Same as for even dashes
367       FillStippled         Background masked by stipple
368
369       Storing a pixmap in a GC might or might not result in a copy being
370       made.  If the pixmap is later used as the destination for a graphics
371       request, the change might or might not be reflected in the GC.  If the
372       pixmap is used simultaneously in a graphics request both as a destina‐
373       tion and as a tile or stipple, the results are undefined.
374
375       For optimum performance, you should draw as much as possible with the
376       same GC (without changing its components).  The costs of changing GC
377       components relative to using different GCs depend on the display hard‐
378       ware and the server implementation.  It is quite likely that some
379       amount of GC information will be cached in display hardware and that
380       such hardware can only cache a small number of GCs.
381
382       The dashes value is actually a simplified form of the more general pat‐
383       terns that can be set with XSetDashes.  Specifying a value of N is
384       equivalent to specifying the two-element list [N, N] in XSetDashes.
385       The value must be nonzero, or a BadValue error results.
386
387       The clip-mask restricts writes to the destination drawable.  If the
388       clip-mask is set to a pixmap, it must have depth one and have the same
389       root as the GC, or a BadMatch error results.  If clip-mask is set to
390       None, the pixels are always drawn regardless of the clip origin.  The
391       clip-mask also can be set by calling the XSetClipRectangles or XSetRe‐
392       gion functions.  Only pixels where the clip-mask has a bit set to 1 are
393       drawn.  Pixels are not drawn outside the area covered by the clip-mask
394       or where the clip-mask has a bit set to 0.  The clip-mask affects all
395       graphics requests.  The clip-mask does not clip sources.  The clip-mask
396       origin is interpreted relative to the origin of whatever destination
397       drawable is specified in a graphics request.
398
399       You can set the subwindow-mode to ClipByChildren or IncludeInferiors.
400       For ClipByChildren, both source and destination windows are addition‐
401       ally clipped by all viewable InputOutput children.  For IncludeInferi‐
402       ors, neither source nor destination window is clipped by inferiors.
403       This will result in including subwindow contents in the source and
404       drawing through subwindow boundaries of the destination.  The use of
405       IncludeInferiors on a window of one depth with mapped inferiors of dif‐
406       fering depth is not illegal, but the semantics are undefined by the
407       core protocol.
408
409       The fill-rule defines what pixels are inside (drawn) for paths given in
410       XFillPolygon requests and can be set to EvenOddRule or WindingRule.
411       For EvenOddRule, a point is inside if an infinite ray with the point as
412       origin crosses the path an odd number of times.  For WindingRule, a
413       point is inside if an infinite ray with the point as origin crosses an
414       unequal number of clockwise and counterclockwise directed path seg‐
415       ments.  A clockwise directed path segment is one that crosses the ray
416       from left to right as observed from the point.  A counterclockwise seg‐
417       ment is one that crosses the ray from right to left as observed from
418       the point.  The case where a directed line segment is coincident with
419       the ray is uninteresting because you can simply choose a different ray
420       that is not coincident with a segment.
421
422       For both EvenOddRule and WindingRule, a point is infinitely small, and
423       the path is an infinitely thin line.  A pixel is inside if the center
424       point of the pixel is inside and the center point is not on the bound‐
425       ary.  If the center point is on the boundary, the pixel is inside if
426       and only if the polygon interior is immediately to its right (x
427       increasing direction).  Pixels with centers on a horizontal edge are a
428       special case and are inside if and only if the polygon interior is
429       immediately below (y increasing direction).
430
431       The arc-mode controls filling in the XFillArcs function and can be set
432       to ArcPieSlice or ArcChord.  For ArcPieSlice, the arcs are pie-slice
433       filled.  For ArcChord, the arcs are chord filled.
434
435       The graphics-exposure flag controls GraphicsExpose event generation for
436       XCopyArea and XCopyPlane requests (and any similar requests defined by
437       extensions).
438

DIAGNOSTICS

440       BadAlloc  The server failed to allocate the requested resource or
441                 server memory.
442
443       BadDrawable
444                 A value for a Drawable argument does not name a defined Win‐
445                 dow or Pixmap.
446
447       BadFont   A value for a Font or GContext argument does not name a
448                 defined Font.
449
450       BadGC     A value for a GContext argument does not name a defined GCon‐
451                 text.
452
453       BadMatch  An InputOnly window is used as a Drawable.
454
455       BadMatch  Some argument or pair of arguments has the correct type and
456                 range but fails to match in some other way required by the
457                 request.
458
459       BadPixmap A value for a Pixmap argument does not name a defined Pixmap.
460
461       BadValue  Some numeric value falls outside the range of values accepted
462                 by the request.  Unless a specific range is specified for an
463                 argument, the full range defined by the argument's type is
464                 accepted.  Any argument defined as a set of alternatives can
465                 generate this error.
466

SEE ALSO

468       AllPlanes(3), XCopyArea(3), XCreateRegion(3), XDrawArc(3), XDraw‐
469       Line(3), XDrawRectangle(3), XDrawText(3), XFillRectangle(3),
470       XQueryBestSize(3), XSetArcMode(3), XSetClipOrigin(3), XSetFillStyle(3),
471       XSetFont(3), XSetLineAttributes(3), XSetState(3), XSetTile(3)
472       Xlib - C Language X Interface
473
474
475
476X Version 11                     libX11 1.6.7                     XCreateGC(3)
Impressum