<HTML>
<HEAD>
<TITLE>XCreateGC</TITLE>
</HEAD>
<BODY>
<PRE>


   Release 6						      XCreateGC(3X11)
							       XLIB FUNCTIONS



   NAME
     XCreateGC,	XCopyGC, XChangeGC, XGetGCValues, XFreeGC, XGContextFromGC,
     XGCValues - create	or free	graphics contexts and graphics context struc-
     ture

   SYNTAX
     GC	XCreateGC(display, d, valuemask, values)
	   Display *display;
	   Drawable d;
	   unsigned long valuemask;
	   XGCValues *values;

     XCopyGC(display, src, valuemask, dest)
	   Display *display;
	   GC src, dest;
	   unsigned long valuemask;

     XChangeGC(display,	gc, valuemask, values)
	   Display *display;
	   GC gc;
	   unsigned long valuemask;
	   XGCValues *values;

     Status XGetGCValues(display, gc, valuemask, values_return)
	   Display *display;
	   GC gc;
	   unsigned long valuemask;
	   XGCValues *values_return;

     XFreeGC(display, gc)
	   Display *display;
	   GC gc;

     GContext XGContextFromGC(gc)
	   GC gc;

   ARGUMENTS

     d	       Specifies the drawable.

     dest      Specifies the destination GC.

     display   Specifies the connection	to the X server.

     gc	       Specifies the GC.

     src       Specifies the components	of the source GC.

     valuemask Specifies which components in the GC are	to be set, copied,
	       changed,	or returned . This argument is the bitwise inclusive
	       OR of zero or more of the valid GC component mask bits.

     values    Specifies any values as specified by the	valuemask.

     values_return
	       Returns the GC values in	the specified XGCValues	structure.


   DESCRIPTION
     The 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
     BadMatch error.

     XCreateGC can generate BadAlloc, BadDrawable, BadFont, BadMatch, BadPix-
     map, and BadValue errors.

     The 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 BadMatch	error results.	The valuemask speci-
     fies which	component to copy, as for XCreateGC.

     XCopyGC can generate BadAlloc, BadGC, and BadMatch	errors.

     The 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 XCreateGC.	 Changing the
     clip-mask overrides any previous XSetClipRectangles request on the	con-
     text. Changing the	dash-offset or dash-list overrides any previous	XSet-
     Dashes request on the context.  The order in which	components are veri-
     fied and altered is server-dependent.  If an error	is generated, a	sub-
     set of the	components may have been altered.

     XChangeGC can generate BadAlloc, BadFont, BadGC, BadMatch,	BadPixmap,
     and BadValue errors.

     The XGetGCValues function returns the components specified	by valuemask
     for the specified GC.  If the valuemask contains a	valid set of GC	mask
     bits (GCFunction, GCPlaneMask, GCForeground, GCBackground,	GCLineWidth,
     GCLineStyle, GCCapStyle, GCJoinStyle, GCFillStyle,	GCFillRule, GCTile,
     GCStipple,	GCTileStipXOrigin, GCTileStipYOrigin, GCFont, GCSubwin-
     dowMode, GCGraphicsExposures, GCClipXOrigin, GCCLipYOrigin,
     GCDashOffset, or GCArcMode) and no	error occurs, 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 GCClipMask and 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 GCFont, GCTile, and GCStipple if the component
     has never been explicitly set by the client.

     The XFreeGC function destroys the specified GC as well as all the asso-
     ciated storage.

     XFreeGC can generate a BadGC error.

   STRUCTURES
     The XGCValues structure contains:

     /*	GC attribute value mask	bits */
     #define   GCFunction		   (1L&lt;&lt;0)
     #define   GCPlaneMask		   (1L&lt;&lt;1)
     #define   GCForeground		   (1L&lt;&lt;2)
     #define   GCBackground		   (1L&lt;&lt;3)
     #define   GCLineWidth		   (1L&lt;&lt;4)
     #define   GCLineStyle		   (1L&lt;&lt;5)
     #define   GCCapStyle		   (1L&lt;&lt;6)

     #define   GCJoinStyle		   (1L&lt;&lt;7)
     #define   GCFillStyle		   (1L&lt;&lt;8)
     #define   GCFillRule		   (1L&lt;&lt;9)
     #define   GCTile			   (1L&lt;&lt;10)
     #define   GCStipple		   (1L&lt;&lt;11)

     #define   GCTileStipXOrigin	   (1L&lt;&lt;12)
     #define   GCTileStipYOrigin	   (1L&lt;&lt;13)
     #define   GCFont			   (1L&lt;&lt;14)
     #define   GCSubwindowMode		   (1L&lt;&lt;15)
     #define   GCGraphicsExposures	   (1L&lt;&lt;16)
     #define   GCClipXOrigin		   (1L&lt;&lt;17)
     #define   GCClipYOrigin		   (1L&lt;&lt;18)
     #define   GCClipMask		   (1L&lt;&lt;19)
     #define   GCDashOffset		   (1L&lt;&lt;20)
     #define   GCDashList		   (1L&lt;&lt;21)
     #define   GCArcMode		   (1L&lt;&lt;22)
     /*	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;

     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 com-
     puted from	the source bits	and the	old destination	bits.  GXcopy is typ-
     ically the	most useful because it will work on a color display, but spe-
     cial applications may use other functions,	particularly in	concert	with
     particular	planes of a color display.  The	16 GC functions, defined in
     &lt;X11/X.h&gt;,	are:
     ______________________________________________
     Function Name     Value   Operation
     ______________________________________________



















   ()


     GXclear		0x0    0
     GXand		0x1    src AND dst
     GXandReverse	0x2    src AND NOT dst
     GXcopy		0x3    src
     GXandInverted	0x4    (NOT src) AND dst
     GXnoop		0x5    dst
     GXxor		0x6    src XOR dst
     GXor		0x7    src OR dst
     GXnor		0x8    (NOT src) AND (NOT
			       dst)
     GXequiv		0x9    (NOT src) XOR dst
     GXinvert		0xa    NOT dst
     GXorReverse	0xb    src OR (NOT dst)
     GXcopyInverted	0xc    NOT src
     GXorInverted	0xd    (NOT src) OR dst
     GXnand		0xe    (NOT src) OR (NOT
			       dst)
     GXset		0xf    1
     ______________________________________________

     Many graphics operations depend on	either pixel values or planes in a
     GC.  The planes attribute is of type long,	and it specifies which planes
     of	the destination	are to be modified, one	bit per	plane.	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.

     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 res-
     tricts the	operation to a subset of planes.  A macro constant AllPlanes
     can be used to refer to all planes	of the screen simultaneously.  The
     result is computed	by the following:

     ((src FUNC	dst) AND plane-mask) OR	(dst AND (NOT plane-mask))

     Range checking is not performed on	the values for foreground, back-
     ground, 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).

     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:

     [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)]

     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).

     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.

     1.	  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.

     2.	  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.

     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 fas-
     ter than the more precisely specified wide	lines.

     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.

     The line-style defines which sections of a	line are drawn:
     LineSolid	     The full path of the line is drawn.

     LineDoub-	     The full path of the line is drawn, but the
     leDash	     even dashes are filled differently	than the
		     odd dashes	(see fill-style) with CapButt
		     style used	where even and odd dashes meet.
     LineOnOffDash   Only the even dashes are drawn, and cap-style
		     applies to	all internal ends of the indivi-
		     dual dashes, except CapNotLast is treated as
		     CapButt.

     The cap-style defines how the endpoints of	a path are drawn:
     CapNotLast	     This is equivalent	to CapButt except that for
		     a line-width of zero the final endpoint is
		     not drawn.

     CapButt	     The line is square	at the endpoint	(perpen-
		     dicular to	the slope of the line) with no
		     projection	beyond.
     CapRound	     The line has a circular arc with the diameter
		     equal to the line-width, centered on the end-
		     point.  (This is equivalent to CapButt for
		     line-width	of zero).

     CapProjecting   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 CapButt for line-width of
		     zero).
     The join-style defines how	corners	are drawn for wide lines:
     JoinMiter	     The outer edges of	two lines extend to meet
		     at	an angle.  However, if the angle is less
		     than 11 degrees, then a JoinBevel join-style
		     is	used instead.

     JoinRound	     The corner	is a circular arc with the diame-
		     ter equal to the line-width, centered on the
		     joinpoint.

     JoinBevel	     The corner	has CapButt endpoint styles with
		     the triangular notch filled.

     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:
     CapNotLast	     thin    The results are device-dependent, but
			     the desired effect	is that	nothing	is
			     drawn.
     CapButt	     thin    The results are device-dependent, but
			     the desired effect	is that	a single
			     pixel is drawn.

     CapRound	     thin    The results are the same as for
			     CapButt/thin.
     CapProjecting   thin    The results are the same as for
			     CapButt/thin.

     CapButt	     wide    Nothing is	drawn.
     CapRound	     wide    The closed	path is	a circle, centered at
			     the endpoint, and with the	diameter
			     equal to the line-width.

     CapProjecting   wide    The closed	path is	a square, aligned
			     with the coordinate axes, centered	at
			     the endpoint, and with the	sides equal
			     to	the line-width.

     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.

     The tile/stipple represents an infinite two-dimensional plane, with the
     tile/stipple replicated in	all dimensions.	 When that plane is superim-
     posed 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 destina-
     tion drawable is specified	in a graphics request.	The tile pixmap	must
     have the same root	and depth as the GC, or	a BadMatch error results.
     The stipple pixmap	must have depth	one and	must have the same root	as
     the GC, or	a BadMatch error results. For stipple operations where the
     fill-style	is FillStippled	but not	FillOpaqueStippled, the	stipple	pat-
     tern 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.

     The fill-style defines the	contents of the	source for line, text, and
     fill requests. For	all text and fill requests (for	example, XDrawText,
     XDrawText16, XFillRectangle, XFillPolygon,	and XFillArc); for line
     requests with line-style LineSolid	(for example, XDrawLine, XDrawSeg-
     ments, XDrawRectangle, XDrawArc); and for the even	dashes for line
     requests with line-style LineOnOffDash or LineDoubleDash, the following
     apply:
     FillSolid		  Foreground

     FillTiled		  Tile



     FillOpaqueStippled	  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

     FillStippled	  Foreground masked by stipple

     When drawing lines	with line-style	LineDoubleDash,	the odd	dashes are
     controlled	by the fill-style in the following manner:
     FillSolid		  Background
     FillTiled		  Same as for even dashes

     FillOpaqueStippled	  Same as for even dashes
     FillStippled	  Background masked by stipple

     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.

     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 upon 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.

     The dashes	value is actually a simplified form of the more	general	pat-
     terns that	can be set with	XSetDashes.  Specifying	a value	of N is
     equivalent	to specifying the two-element list [N, N] in XSetDashes.  The
     value must	be nonzero, or a BadValue error	results.

     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 BadMatch error results.  If clip-mask	is set to
     None, the pixels are always drawn regardless of the clip origin.  The
     clip-mask also can	be set by calling the XSetClipRectangles or XSetRe-
     gion 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.

     You can set the subwindow-mode to ClipByChildren or IncludeInferiors.
     For ClipByChildren, both source and destination windows are additionally
     clipped by	all viewable InputOutput children. For IncludeInferiors, nei-
     ther 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 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.

     The fill-rule defines what	pixels are inside (drawn) for paths given in
     XFillPolygon requests and can be set to EvenOddRule or WindingRule.  For
     EvenOddRule, a point is inside if an infinite ray with the	point as ori-
     gin crosses the path an odd number	of times. For 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 unin-
     teresting because you can simply choose a different ray that is not
     coincident	with a segment.

     For both EvenOddRule and 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 boun-
     dary. 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).

     The arc-mode controls filling in the XFillArcs function and can be	set
     to	ArcPieSlice or ArcChord.  For ArcPieSlice, the arcs are	pie-slice
     filled.  For ArcChord, the	arcs are chord filled.

     The graphics-exposure flag	controls GraphicsExpose	event generation for
     XCopyArea and XCopyPlane requests (and any	similar	requests defined by
     extensions).

   DIAGNOSTICS

     BadAlloc  The server failed to allocate the requested resource or server
	       memory.

     BadDrawable
	       A value for a Drawable argument does not	name a defined Window
	       or Pixmap.

     BadFont   A value for a Font or GContext argument does not	name a
	       defined Font.

     BadGC     A value for a GContext argument does not	name a defined GCon-
	       text.

     BadMatch  An InputOnly window is used as a	Drawable.

     BadMatch  Some argument or	pair of	arguments has the correct type and
	       range but fails to match	in some	other way required by the
	       request.

     BadPixmap A value for a Pixmap argument does not name a defined Pixmap.

     BadValue  Some numeric value falls	outside	the range of values accepted
	       by the request.	Unless a specific range	is specified for an
	       argument, the full range	defined	by the argument's type is
	       accepted.  Any argument defined as a set	of alternatives	can
	       generate	this error.

   SEE ALSO
     AllPlanes(3X11), XCopyArea(3X11), XCreateRegion(3X11), XDrawArc(3X11),
     XDrawLine(3X11), XDrawRectangle(3X11), XDrawText(3X11),
     XFillRectangle(3X11), XQueryBestSize(3X11), XSetArcMode(3X11),
     XSetClipOrigin(3X11), XSetFillStyle(3X11),	XSetFont(3X11),
     XSetLineAttributes(3X11), XSetState(3X11),	XSetTile(3X11)
     Xlib - C Language X Interface











</PRE>
</BODY>
</HTML>
