Next: , Previous: Drawables, Up: Top

4 Graphics Context

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.

— Function: x:create-gc drawable field-name value ...

Creates and returns graphics context. The graphics context can be used with any destination drawable having the same root and depth as the specified drawable.

— Function: x:gc-set! graphics-context field-name value ...

Changes the components specified by field-names for the specified graphics-context. The restrictions are the same as for x:create-gc. The order in which components are verified and altered is server dependent. If an error occurs, a subset of the components may have been altered.

— Function: x:copy-gc-fields! gcontext-src gcontext-dst field-name ...

Copies the components specified by field-names from gcontext-src to gcontext-dst. Gcontext-src and gcontext-dst must have the same root and depth.

— Function: x:gc-ref graphics-context field-name ...

Returns a list of the components specified by field-names ... from the specified graphics-context.

GC Attributes

Both x:create-gc and x:change-gc take one argument followed by pairs of arguments, where the first is one of the property-name symbols (or its top-level value) listed below; and the second is the value to associate with that property.

— Attribute: x:GC-Function

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. x:G-Xcopy 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 functions are:

     x:G-Xclear           0
     x:G-Xand             (AND src dst)
     x:G-Xand-Reverse     (AND src (NOT dst))
     x:G-Xcopy            src
     x:G-Xand-Inverted    (AND (NOT src) dst)
     x:G-Xnoop            dst
     x:G-Xxor             (XOR src dst)
     x:G-Xor              (OR src dst)
     x:G-Xnor             (AND (NOT src) (NOT dst))
     x:G-Xequiv           (XOR (NOT src) dst)
     x:G-Xinvert          (NOT dst)
     x:G-Xor-Reverse      (OR src (NOT dst))
     x:G-Xcopy-Inverted   (NOT src)
     x:G-Xor-Inverted     (OR (NOT src) dst)
     x:G-Xnand            (OR (NOT src) (NOT dst))
     x:G-Xset             1
— Attribute: x:GC-Plane-Mask

Many graphics operations depend on either pixel values or planes in a GC. The planes attribute is an integer which 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 integer. 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 restricts the operation to a subset of planes. x:All-Planes can be used to refer to all planes of the screen simultaneously. The result is computed by the following:

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

Range checking is not performed on a plane-mask value. It is simply truncated to the appropriate number of bits.

— Attribute: x:GC-Foreground
— Attribute: x:GC-Background

Range checking is not performed on the values for foreground or background. They are simply truncated to the appropriate number of bits.

Note that foreground and background are not initialized to any values likely to be useful in a window.

— Attribute: x:GC-Line-Width

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

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.

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.

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 linewidth of zero.

— Attribute: x:GC-Line-Style

The line-style defines which sections of a line are drawn:

The full path of the line is drawn.
The full path of the line is drawn, but the even dashes are filled differently from the odd dashes (see fill-style) with x:Cap-Butt style used where even and odd dashes meet.
Only the even dashes are drawn, and cap-style applies to all internal ends of the individual dashes, except x:Cap-Not-Last is treated as x:Cap-Butt.

— Attribute: x:GC-Cap-Style

The cap-style defines how the endpoints of a path are drawn:

This is equivalent to x:Cap-Butt except that for a line-width of zero the final endpoint is not drawn.
The line is square at the endpoint (perpendicular to the slope of the line) with no projection beyond.
The line has a circular arc with the diameter equal to the line-width, centered on the endpoint. (This is equivalent to x:Cap-Butt for line-width of zero).
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 x:Cap-Butt for line-width of zero).

— Attribute: x:GC-Join-Style

The join-style defines how corners are drawn for wide lines:

The outer edges of two lines extend to meet at an angle. However, if the angle is less than 11 degrees, then a x:Join-Bevel join-style is used instead.
The corner is a circular arc with the diameter equal to the line-width, centered on the x:Join-point.
The corner has x:Cap-Butt endpoint styles with the triangular notch filled.

— Attribute: x:GC-Fill-Style

The fill-style defines the contents of the source for line, text, and fill requests. For all text and fill requests (for example, X:Draw-Text, X:Fill-Rectangle, X:Fill-Polygon, and X:Fill-Arc); for line requests with linestyle x:Line-Solid (for example, X:Draw-Line, X:Draw-Segments, X:Draw-Rectangle, X:Draw-Arc); and for the even dashes for line requests with line-style x:Line-On-Off-Dash or x:Line-Double-Dash, the following apply:

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
Foreground masked by stipple

When drawing lines with line-style x:Line-Double-Dash, the odd dashes are controlled by the fill-style in the following manner:

Same as for even dashes
Same as for even dashes
Background masked by stipple

— Attribute: x:GC-Fill-Rule

The fill-rule defines what pixels are inside (drawn) for paths given in X:Fill-Polygon requests and can be set to x:Even-Odd-Rule or x:Winding-Rule.

A point is inside if an infinite ray with the point as origin crosses the path an odd number of times.
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.

For both x:Even-Odd-Rule and x:Winding-Rule, 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).

— Attribute: x:GC-Tile
— Attribute: x:GC-Stipple

The tile/stipple represents an infinite two-dimensional plane, with the tile/stipple replicated in all dimensions.

The tile pixmap must have the same root and depth as the GC, or an error results. The stipple pixmap must have depth one and must have the same root as the GC, or an error results. For stipple operations where the fill-style is x:Fill-Stippled but not x:Fill-Opaque-Stippled, 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.

— Attribute: x:GC-Tile-Stip-X-Origin
— Attribute: x:GC-Tile-Stip-Y-Origin

When the tile/stipple plane is superimposed on a 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 origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request.

— Attribute: x:GC-Font

The font to be used for drawing text.

— Attribute: x:GC-Subwindow-Mode

You can set the subwindow-mode to x:Clip-By-Children or x:Include-Inferiors.

Both source and destination windows are additionally clipped by all viewable Input-Output children.
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 x:Include-Inferiors on a window of one depth with mapped inferiors of differing depth is not illegal, but the semantics are undefined by the core protocol.

— Attribute: x:GC-Graphics-Exposures

The graphics-exposure flag controls x:Graphics-Expose event generation for X:Copy-Area and X:Copy-Plane requests (and any similar requests defined by extensions).

— Attribute: x:GC-Clip-X-Origin
— Attribute: x:GC-Clip-Y-Origin

The clip-mask origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request.

— Attribute: x:GC-Clip-Mask

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 an error results. If clip-mask is set to x:None, the pixels are always drawn regardless of the clip origin. The clip-mask also can be set by calling X:Set-Region. 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.

— Attribute: x:GC-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.

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.

— Attribute: x:GC-Dash-List

There must be at least one element in the specified dash-list. 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. Specifying an odd-length list is equivalent to specifying the same list concatenated with itself to produce an even-length list.

— Attribute: x:GC-Arc-Mode

The arc-mode controls filling in the X:Fill-Arcs function and can be set to x:Arc-Pie-Slice or x:Arc-Chord.

The arcs are pie-slice filled.
The arcs are chord filled.