(y + font-descent - 1).
A font is not guaranteed to have any properties. Whether
a property value is signed or unsigned must be derived
from a prior knowledge of the property. When possible,
fonts should have at least the following properties (note
that the trailing colon is not part of the name, and that
upper/lower case matters).
MIN_SPACE: CARD32
The minimum interword spacing, in pixels.
NORM_SPACE: CARD32
The normal interword spacing, in pixels.
MAX_SPACE: CARD32
The maximum interword spacing, in pixels
SUBSCRIPT_X: INT32
SUBSCRIPT_Y: INT32
Offsets from the character origin where subscripts
should begin, in pixels. If the origin is at [x,y],
then subscripts should begin at [x + SubscriptX,
y + SubscriptY].
UNDERLINE_POSITION: INT32
Y offset from the baseline to the top of an underline,
in pixels. If the baseline is Y-coordinate y, then
the top of the underline is at (y +
UnderlinePosition).
UNDERLINE_THICKNESS: CARD32
Thickness of the underline, in pixels.
STRIKEOUT_ASCENT: INT32
STRIKEOUT_DESCENT: INT32
Vertical extents for boxing or voiding characters, in
pixels. If the baseline is at Y-coordinate y, then
the top of the strikeout box is at (y -
StrikeoutAscent), and the height of the box is
(StrikeoutAscent + StrikeoutDescent).
ITALIC_ANGLE: INT32
The angle of characters in the font, in degrees
scaled by 64, relative to the three-oclock position
from the character origin, with positive indicating
counterclockwise motion (as in Arc requests).
X_HEIGHT: INT32
"1 ex" as in TeX, but expressed in units of pixels.
Often the height of lowercase x.
QUAD_WIDTH: INT32
"1 em" as in TeX, but expressed in units of pixels.
Often the width of the digits 0-9.
WEIGHT: CARD32
The weight or boldness of the font, expressed as a
value between 0 and 1000.
POINT_SIZE: CARD32
The point size, expressed in 1/10ths, of this font at
the ideal resolution. There are 72.27 points to the
inch.
RESOLUTION: CARD32
The number of pixels per point, expressed in 1/100ths,
at which this font was created.
For a character origin at [x,y], the bounding box of a
character,i.e., the smallest rectangle enclosing the
character's shape, described in terms of CHARINFO
components, is a rectangle with its upper left corner at
[x + left-side-bearing, y - ascent]
with a width of
right-side-bearing - left-side-bearing
and a height of
ascent + descent
and the origin for the next character is defined to be
[x + character-width, y]
Note that the baseline is logically viewed as being just
below non-descending characters (when descent is zero,
only pixels with Y-coordinates less than y are drawn),
and that the origin is logically viewed as being
coincident with the left edge of a non-kerned character
(when left-side-bearing is zero, no pixels with
X-coordinate less than x are drawn).
Note that CHARINFO metric values can be negative.
A non-existent character is represented with all CHARINFO
components zero.
The interpretation of the per-character attributes field
is undefined by the core protocol.
QueryTextExtents
font: FONT or GCONTEXT
items: STRING16
=>
draw-direction: {LeftToRight, RightToLeft}
font-ascent: INT16
font-descent: INT16
overall-ascent: INT16
overall-descent: INT16
overall-width: INT32
overall-left: INT32
overall-right: INT32
Errors: Font
Returns the logical extents of the specified string of
characters in the specified font. Draw-direction,
font-ascent, and font-descent are as described in
QueryFont. Overall-ascent is the maximum of the ascent
metrics of all characters in the string, and
overall-descent is the maximum of the descent metrics.
Overall-width is the sum of the character-width metrics
of all characters in the string. For each character in
the string, let W be the sum of the character-width
metrics of all characters preceding it in the string,
let L be the left-side-bearing metric of the character
plus W, and let R be the right-side-bearing metric of
the character plus W. Overall-left is the minimum L of
all characters in the string, and overall-right is the
maximum R.
For fonts defined with linear indexing rather than
two-byte matrix indexing, the server will interpret each
CHAR2B as a 16-bit number that has been transmitted most
significant byte first (i.e., byte1 of the CHAR2B is
taken as the most significant byte).
If the font has no defined default-char, then undefined
characters in the string are taken to have all zero
metrics.
ListFonts
pattern: STRING8
max-names: CARD16
=>
names: LISTofSTRING8
Returns a list of length at most max-names, of names of
fonts matching the pattern. The pattern should use the
ASCII encoding, and upper/lower case does not matter.
In the pattern, the '?' character (octal value 77) will
match any single character, and the character '*' (octal
value 52) will match any number of characters. The
returned names are in lower case.
ListFontsWithInfo
pattern: STRING8
max-names: CARD16
=>
fonts: LISTofFONTDATA
where
FONTDATA: [name: STRING8
info: FONTINFO]
FONTINFO: <same type definition as in QueryFont>
Like ListFonts, but also returns information about each
font. The information returned for each font is
identical to what QueryFont would return (except that the
per-character metrics are not returned).
SetFontPath
path: LISTofSTRING8
Errors: Value
Defines the search path for font lookup. There is only one
search path per server, not one per client. The
interpretation of the strings is operating system dependent,
but they are intended to specify directories to be
searched in the order listed.
Setting the path to the empty list restores the default
path defined for the server.
As a side-effect of executing this request, the server
is guaranteed to flush all cached information about fonts
for which there currently are no explicit resource ids
allocated.
The meaning of an error from this request is system
specific.
GetFontPath
=>
path: LISTofSTRING8
Returns the current search path for fonts.
CreatePixmap
pid: PIXMAP
drawable: DRAWABLE
depth: CARD8
width, height: CARD16
Errors: IDChoice, Drawable, Value, Alloc
Creates a pixmap, and assigns the identifier pid to it.
Width and height must be non-zero. Depth must be one of
the depths supported by root of the specified drawable.
The initial contents of the pixmap are undefined.
It is legal to pass an InputOnly window as a drawable to
this request.
FreePixmap
pixmap: PIXMAP
Errors: Pixmap
Deletes the association between the resource id and the
pixmap. The pixmap storage will be freed when no other
resource references it.
CreateGC
cid: GCONTEXT
drawable: DRAWABLE
value-mask: BITMASK
value-list: LISTofVALUE
Errors: IDChoice, Drawable, Pixmap, Font, Match, Value, Alloc
Creates a graphics context, and assigns the identifier cid to
it. The gcontext can be used with any destination drawable
having the same root and depth as the specified drawable.
The value-mask and value-list specify which components are to
be explicitly initialized. The context components are:
alu-function: {Clear, And, AndReverse, Copy, AndInverted,
Noop, Xor, Or, Nor, Equiv, Invert,
OrReverse, CopyInverted, OrInverted,
Nand, Set}
plane-mask: CARD32
foreground: CARD32
background: CARD32
line-width: CARD16
line-style: {Solid, OnOffDash, DoubleDash}
cap-style: {NotLast, Butt, Round, Projecting}
join-style: {Miter, Round, Bevel}
fill-style: {Solid, Tiled, OpaqueStippled, Stippled}
fill-rule: {EvenOdd, Winding}
arc-mode: {Chord, PieSlice}
tile: PIXMAP
stipple: PIXMAP
tile-stipple-x-origin: INT16
tile-stipple-y-origin: INT16
font: FONT
subwindow-mode: {ClipByChildren, IncludeInferiors}
graphics-exposures: BOOL
clip-x-origin: INT16
clip-y-origin: INT16
clip-mask: PIXMAP or None
dash-offset: CARD16
dash-list: CARD8
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. That is, the result is
((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
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 meanings of the alu-functions are:
Clear 0
And src AND dst
AndReverse src AND (NOT dst)
Copy src
AndInverted (NOT src) AND dst
NoOp dst
Xor src XOR dst
Or src OR dst
Nor (NOT src) AND (NOT dst)
Equiv (NOT src) XOR dst
Invert NOT dst
OrReverse src OR (NOT dst)
CopyInverted NOT src
OrInverted (NOT src) OR dst
NAnd (NOT src) OR (NOT dst)
Set 1
Line-width is measured in pixels and can be greater than or
equal to one (a "wide" line) or the special value zero (a
"thin" line).
Wide lines are drawn centered on the path described by the
graphics request. Unless otherwise specified by the join 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)]
where 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 hence 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 is immediately below (y increasing direction).
Note that this description is a mathematical model
describing the pixels that are drawn for a wide line and
does not imply that trigonometry is required to implement
such a model. Real or fixed point arithmetic is
recommended for computing the corners of the line endpoints
for lines greater than one pixel in width.
Thin lines (zero line-width) are "one pixel wide" lines drawn
using an unspecified, device dependent algorithm (for
example, Bresenham). There are only two constraints on this
algorithm. First, if a line is drawn unclipped from [x1,y1]
to [x2,y2] and another line is drawn unclipped from [x1+dx,
y1+dy] to [x2+dx,y2+dy], then 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. Second, 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.
Note that 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 and join styles, but this property
is not guaranteed for thin lines. Also note that "jags" in
adjacent wide lines will always line up properly, but this
property is not guaranteed for thin lines. A line-width of
zero differs from a line-width of one in which pixels are
drawn. In general, drawing a thin line will be faster than
drawing a wide line of width one, but thin lines may not mix
well aesthetically 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 segments of a line are drawn:
Solid: the full path of the line is drawn
DoubleDash: the full path of the line is drawn, but the
segments defined by the even dashes are
filled differently than the segments defined
by the odd dashes (see fill-style)
OnOffDash: only the segments defined by the even dashes
are drawn, and cap-style applies to each
individual segment (except NotLast is treated
as Butt for internal caps)
The cap-style defines how the endpoints of a path are drawn:
NotLast: equivalent to Butt, except that for a
line-width of zero or one the final endpoint is
not drawn
Butt: square at the endpoint, with no projection beyond
Round: a circular arc with diameter equal to the
line-width, centered on the endpoint; equivalent
to Butt for line-width zero or one
Projecting: square at the end, but the path continues
beyond the endpoint for a distance equal to
half the line-width; equivalent to Butt for
line-width zero or one
The join-style defines how corners are drawn for wide lines:
Miter: the outer edges of the two lines extend to meet at
an angle
Round: a circular arc with diameter equal to the
line-width, centered on the joinpoint
Bevel: Butt endpoint styles, and then the triangular
"notch" filled
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
gcontext (else a Match error). The stipple pixmap must have
depth one, and must have the same root as the gcontext (else
a Match error). For stipple operations, the stipple pattern
is tiled in a single plane, and acts as an additional clip
mask to be ANDed with the clip-mask. Any size pixmap can be
used for tiling or stippling, although some sizes may be
faster to use than others.
The fill-style defines the contents of the source for line,
text, and fill requests. For all text and fill requests
(PolyText8, PolyText16, PolyFillRectangle, FillPoly,
PolyFillArc), for line requests (PolyLine, PolySegment,
PolyRectangle, PolyArc) with line-style Solid, and for the
even dashes for line requests with line-style OnOffDash or
DoubleDash:
Solid: foreground
Tiled: tile
OpaqueStippled: 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
Stippled: foreground masked by stipple
For the odd dashes for line requests with line-style
DoubleDash:
Solid: background
Tiled: same as for even dashes
OpaqueStippled: same as for even dashes
Stippled: background masked by stipple
The dash-list value allowed here is actually a simplified
form of the more general patterns that can be set with
SetDashes.Specifying a value of N here is equivalent to
specifying the two element list [N, N] in SetDashes. The
value must be non-zero. The meaning of dash-offset and
dash-list are explained in the SetDashes request.
The clip-mask restricts writes to the destination drawable;
only pixels where the clip-mask has a one bit are drawn. It
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. If a pixmap is specified as the clip-mask,
it must have depth one and have the same root as the gcontext
(else a Match error). The clip-mask can also be set with the
SetClipRectangles request.
For ClipByChildren, both source and destination windows are
additionally clipped by all viewable InputOutput children.
For IncludeInferiors, neither source nor destination window
is clipped by inferiors; this will result in drawing through
subwindow boundaries. The use of IncludeInferiors on a window
of one depth with mapped inferiors of differing depth is not
illegal, but the semantics isundefined by the core protocol.
The fill-rule defines what pixels are inside (i.e., are
drawn) for paths given in FillPoly requests. EvenOdd means
a point is inside if an infinite ray with the point as origin
crosses the path an odd number of times. For Winding, a
point is inside if an infinite ray with the point as origin
crosses an unequal number of clockwise and counterclockwise
directed path segments. For both rules, 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 along 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 PolyFillArc request.
The graphics-exposures flag controls GraphicsExposure event
generation for CopyArea and CopyPlane requests (and any
similar requests defined by extensions).
The default component values are:
function: Copy
plane-mask: all ones
foreground: 0
background: 1
line-width: 0
line-style: Solid
cap-style: Butt
join-style: Miter
fill-style: Solid
full-rule: EvenOdd
arc-mode: PieSlice
tile: pixmap of unspecified size filled with forground
pixell (i.e., client specified pixel if any,
else 0)
stipple: pixmap of unspecified size filled with ones
tile-stipple-x-origin: 0
tile-stipple-y-origin: 0
font: <implementation dependent>
subwindow-mode: ClipByChildren
graphics-exposures: True
clip-x-origin: 0
clip-y-origin: 0
clip-mask: None
dash-offset: 0
dash-list: 4 (i.e., the list [4, 4])
Storing a pixmap in a gcontext 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 gcontext. If the pixmap is used
simultaneously in a graphics request as both a destination
and as a tile or stipple. the results are not defined.
It is quite likely that some amount of gcontext information
will be cached in display hardware, and that such hardware
can only cache a small number of gcontexts. Given the number
and complexity of components, clients should view switching
between gcontexts with nearly identical state as
significantly more expensive than making minor changes to a
single gcontext.
ChangeGC
gc: GCONTEXT
value-mask: BITMASK
value-list: LISTofVALUE
Errors: GContext, Pixmap, Font, Match, Value, Alloc
Changes components in gc. The value-mask and value-list
specify which components are to be changed. The values and
restrictions are the same as for CreateGC.
Changing the clip-mask also overrides any previous
SetClipRectangles request on the context. Changing the
dash-offset or dash-list overrides any previous SetDashes
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.
CopyGC
src-gc, dst-gc: GCONTEXT
value-mask: BITMASK
Errors: GContext, Value, Match, Alloc
Copies components from src-gc to dst-gc. The value-mask
specifies which components to copy, as for CreateGC. The
two gcontexts must have the same root and the same depth
(else a Match error).
SetDashes
gc: GCONTEXT
dash-offset: CARD16
dash-list: LISTofCARD8
Errors: GContext, Value, Alloc
Sets the dash-offset and dash-list in gc for dashed line
styles. The initial and alternating elements of the
dash-list are the "even" dashes, the others are the
"odd" dashes. All of the elements must be non-zero.
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 segments combined with
a join-style, but is reset to the dash-offset each time a
cap-style is applied.
SetClipRectangles
gc: GCONTEXT
clip-x-origin, clip-y-origin: INT16
rectangles: LISTofRECTANGLE
ordering: {UnSorted, YSorted, YXSorted, YXBanded}
Errors: GContext, Value, Alloc, Match
Changes clip-mask in gc to the specified list of rectangles
and sets the clip origin. Output will be 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 non-intersecting, or graphics
results will be undefined.
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 server may generate a Match error, but is not
required to do so; if no error is generated, the graphics
results are undefined. UnSorted means the rectangles are in
arbitrary order. YSorted means that the rectangles are
non-decreasing in their Y origin. YXSorted additionally
constrains YSorted order in that all rectangles with an equal
Y origin are non-decreasing in their X origin. YXBanded
additionally constrains YXSorted by requiring that for every
possible Y scanline, all rectangles that include that
scanline have identical Y origins and Y extents.
FreeGC
gc: GCONTEXT
Errors: GContext
Deletes the association between the resource id and the
gcontext, and destroys the gcontext.
ClearToBackground
window: WINDOW
x, y: INT16
width, height: CARD16
exposures: BOOL
Errors: Window, Value, Match
The x and y coordinates are relative to the window's origin,
and specify the upper left corner of the rectangle. If width
is zero, it is replaced with the current width of the window
minus x. If height is zero, it is replaced with the current
height of the window minus y. If the window has a defined
background tile, the rectangle is tiled with a plane-mask of
all ones and alu-function of Copy. If the window has
background None, the contents of the window are not changed.
In eithercase, if exposures is True, then one or more
exposure events are generated for regions of the rectangle
that are eithervisible or are being retained in a backing
store.
It is a Match error to use an InputOnly window in this
request.
CopyArea
src-drawable, dst-drawable: DRAWABLE
gc: GCONTEXT
src-x, src-y: INT16
width, height: CARD16
dst-x, dst-y: INT16
Errors: Drawable, GContext, Match
Combines the specified rectangle of src-drawable with the
specified rectangle of dst-drawable. The src-x and src-y
coordinates are relative to src-drawable's origin, dst-x and
dst-y are relative to dst-drawable's origin, each pair
specifying the upper left corner of the rectangle.
Src-drawable must have the same root and the same depth as
dst-drawable (else a Match error).
If regions of the source rectangle are obscured and have not
been retained by the server, or if regions outside the
boundaries of the source drawable are specified, then the
following occurs. If the dst-drawable is a window with a
background of other than None, the corresponding regions of
the destination are tiled (with plane-mask of ones and
alu-function Copy) with that background. Regardless, if
graphics-exposures in gc is True, GraphicsExposure events
for the corresponding desitnation regions are generated.
If graphics-exposures if True but no regions are exposed,
then a NoExposure event is generated.
GC components: alu-function, plane-mask, foreground,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
CopyPlane
scr-drawable, dst-drawable: DRAWABLE
GC:Gcontext
src-x, src-y: INT16
width, height: CARD16
dst-x, dst-y: INT16
bit-plane: CARD32
Errors: Drawable, GContext, Value, Match
Src-drawable must have the same root as dst-srawable (else
a match error), but need not have the same depth.
Bit-plane must have exactly one bit set. Effectively, that
plane of the src-drawable and the fore-ground/background
pixels in gc are combined to form a pixmap of the same
depth as dst-drawable, and the equivalent of a CopyArea is
performed, with all the same exposure semantics.
GC components: alu-function, plan-mask, foreground,
background, subwindow-mode, graphics-exposures,
clip-x-origin, clip-y-origin, clip-mask
PolyPoint
drawable: DRAWABLE
gc: GCONTEXT
coordinate-mode: {Origin, Previous}
points: LISTofPOINT
Errors: Drawable, GContext, Value, Match
Combines the foreground pixel in gc with the pixel at each
point in the drawable. The points are drawn in the order
listed.
The first point is always relative to the drawable's origin;
the rest are relative either to that origin or the previous
point, depending on the coordinate-mode.
GCcomponents: alu-function, plane-mask, foreground,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
PolyLine
drawable: DRAWABLE
gc: GCONTEXT
coordinate-mode: {Origin, Previous}
points: LISTofPOINT
Errors: Drawable, GContext, Value, Match
Draws lines between each pair of points (point[i], point
[i+1]). The lines are drawn in the order listed. The lines
join correctly at all intermediate points, and if the first
and last points coincide, the first and last lines also join
correctly.
For any given line, no pixel is drawn more than once. If
thin (zero line-width) lines intersect, the intersecting
pixels are drawn multiple times. If wide lines intersect,
the intersecting pixels are drawn only once, as though the
entire PolyLine were a single filled shape.
The first point is always relative to the drawable's origin;
the rest are relative either to that origin or the previous
point, depending on the coordinate-mode.
GC components: alu-function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset,dash-list
PolySegment
drawable: DRAWABLE
gc: GCONTEXT
segments: LISTofSEGMENT
where SEGMENT: [x1, y1, x2, y2: INT16]
Errors: Drawable, GContext, Match
For each segment, draws a line between [x1, y1] and [x2, y2].
The lines are drawn in the order listed. No joining is
performed at coincident end points. For any given line, no
pixel is drawn more than once. If lines intersect, the
intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, line-width,
line-style, cap-style, fill-style, subwindow-mode,
clip-x-origin, clip-y-origin,clip-mask
GC mode-dependent components: foreground, background, tile,
stipple,tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, dash-list
PolyRectangle
drawable: DRAWABLE
gc: GCONTEXT
rectangles: LISTofRECTANGLE
Errors: Drawable, GContext, Match
Draws the outlines of the specified rectangles, as if a
five-point PolyLine were specified for each rectangle. The x
and y coordinates of each rectangle are relative to the
drawable's origin, and define the upper left corner of the
rectangle.
The rectangles are drawn in the order listed. For any given
rectangle, no pixel is drawn more than once. If rectangles
intersect, the intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, line-width,
line-style, join-style, fill-style, subwindow-mode,
clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, dash-list
PolyArc
drawable: DRAWABLE
gc: GCONTEXT
arcs: LISTofARC
Errors: Drawable, GContext, Match
Draws circular or elliptical arcs. Each arc is specified by
a rectangle and two angles. The x and y coordinates are
relative to the origin of the drawable, and define the upper
left corner of the rectangle. The center of the circle or
ellipse is the center of the rectangle, and the major and
minor axes are specified by the width and height,
respectively. The angles are signed integers in degrees
scaled by 64, with positive indicating counterclockwise
motion and negative indicating clockwise motion. The start
of the arc is specified by angle1 relative to the
three-oclock position from the center, and the path and
extent of the arc is specified by angle2 relative to the
start of the arc. If the magnitude of angle2 is greater
than 360 degrees, it is truncated to 360 degrees.
The arcs are drawn in the order listed. If the last point in
one arc coincides with the first point in the following arc,
the two arcs will join correctly. If the first point in the
first arc coincides with the last point in the last arc, the
two arcs will join correctly. For any given arc, no pixel is
drawn more than once. If two arcs join correctly and the
line-width is greater than zero and the arcs intersect, no
pixel is drawn more than once. Otherwise, the intersecting
pixels of intersecting arcs are drawn multiple times.
Specifying an arc with one endpoint and a clockwise extent
draws the same pixels as specifying the other endpoint and an
equivalent counterclockwise extent, except as it affects
joins.
By specifying one axis to be zero, a horizontal or vertical
line can be drawn.
Angles are computed based solely on the coordinate system,
ignoring the aspect ratio.
GC components: alu-function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background, tile,
stipple,tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, dash-list
FillPoly
drawable: DRAWABLE
gc: GCONTEXT
shape: {Complex, Nonconvex, Convex}
coordinate-mode: {Origin, Previous}
points: LISTofPOINT
Errors: Drawable, GContext, Match, Value
Fills the region closed by the specified path. The path is
closed automatically if the last point in the list does not
coincide with the first point. No pixel of the region is
drawn more than once.
The first point is always relative to the drawable's origin;
the rest are relative either to that origin or the previous
point, depending on the coordinate-mode.
The shape parameter may be used by the server to improve
performance. Complex means the path may self-intersect.
Nonconvex means the path does not self-intersect, but the
shape is not wholly convex. If known by the client,
specifying Nonconvex over Complex may improve performance. If
Nonconvex is specified for a self-intersecting path, the
graphics results are undefined.
Convex means the path is wholly convex. If known by the
client, specifying Convex can improve performance. If Convex
is specified for a path that is not convex, the graphics
results are undefined.
GC components: alu-function, plane-mask, fill-style,
fill-rule, subwindow-mode, clip-x-origin, clip-y-origin,
clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PolyFillRectangle
drawable: DRAWABLE
gc: GCONTEXT
rectangles: LISTofRECTANGLE
Errors: Drawable, GContext, Match
Fills the specified rectangles. The x and y coordinates of
each rectangle are relative to the drawable's origin, and
define the upper left corner of the rectangle.
The rectangles are drawn in the order listed. For any given
rectangle, no pixel is drawn more than once. If rectangles
intersect, the intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, fill-style,
fill-rule, subwindow-mode, clip-x-origin, clip-y-origin,
clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PolyFillArc
drawable: DRAWABLE
gc: GCONTEXT
arcs: LISTofARC
Errors: Drawable, GContext, Match
For each arc, fills the region closed by the specified arc
and one or two line segments, depending on the arc-mode. For
Chord, the single line segment joining the endpoints of the
arc is used. For PieSlice, the two line segments joining the
endpoints of the arc with the center point are used. The
arcs are as specified in the PolyArc request.
The arcs are filled in the order listed. For any given arc,
no pixel is drawn more than once. If regions intersect, the
intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, fill-style,
fill-rule, arc-mode, subwindow-mode, clip-x-origin,
clip-y-origin, clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PutImage
drawable: DRAWABLE
gc: GCONTEXT
depth: CARD8
width, height: CARD16
dst-x, dst-y: INT16
left-pad: CARD8
format: {Bitmap, XYPixmap, ZPixmap}
bits: <bits>
Errors: Drawable, GContext, Match, Value, Alloc
Combines an image with a rectangle of the drawable. The
dst-x and dst-y coordinates are relative to the drawable's
origin.
If Bitmap format is used, then depth must be one (else a
Match error) and the image must be in XYFormat. The
foreground pixel in gc defines the source for one bits in the
image, and the background pixel defines the source for the
zero bits.
For XYPixmap and ZPixmap, depth must match the depth of
drawable (else a Match error). For XYPixmap, the image must
be sent in XYFormat. For ZPixmap, the image must be sent in
the ZFormat defined for the given depth.
The left-pad must be zero for ZPixmap format. For Bitmap and
XYPixmap format, left-pad must be less than
bitmap-format-scanline-pad (as given in the server connection
setup info). The first left-pad bits in every scanline are
to be ignored by the server; the actual image begins that
many bits into the data. The width argument defines the width
of the actual image, and does not include left-pad.
GC components: alu-function, plane-mask, subwindow-mode,
clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background
GetImage
drawable: DRAWABLE
x, y: INT16
width, height: CARD16
plane-mask: CARD32
format: {XYFormat, ZFormat}
=>
depth: CARD8
visual: VISUALID or None
bits: <bits>
Errors: Drawable, Value, Match
Returns the contents of the given rectangle of the drawable
in the given format. The x and y coordinates are relative to
the drawable's origin, and define the upper left corner of
the rectangle. If XYFormat is specified, only the bit planes
specified in plane-mask are transmitted. If ZFormat is
specified, then bits in all planes not specified in
plane-mask transmitted as zero. The returned depth specifies
the number of bits per pixel of the image. If the drawable
is a window, its visual type is returned; if the drawable
is a pixmap,the visual is None.
If the drawable is a window, the window must be mapped, and
it must be the case that, if there were no inferiors or
overlapping windows, the specified rectangle of the window
would be fully visible on the screen will include any
visible portions of inferiors or overlapping windows
contained in the rectangle, but if these windows are of
different depth than the specified window, the contents
returned for them are not defined by the core protocol.
PolyText8
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
items: LISTofTEXTITEM8
where
TEXTITEM8: TEXTELT8 or FONT
TEXTELT8: [delta: INT8
string: STRING8]
Errors: Drawable, GContext, Match, Font
The x and y coordinates are relative to drawable's origin,
and specify the baseline starting position (the initial
character origin). Each text item is processed in turn. A
font item causes the font to be stored in gc, and to be
used for subsequent text; switching among fonts with
differing draw-directions is permitted. A text element
delta specifies an additional change in the position along
the x axis before the string is drawn; the delta is always
added to the character origin (not added or subtracted based
on the draw-direction of the current font). Each character
image, as defined by the a font in gc, is treated as an
additional mask for a fill operation on the drawable.
All contained FONTs are always transmitted most significant
byte first.
If a Font error is generated for an item, the previous items
may have been drawn.
For fonts defined with two-byte matrix indexing, each STRING8
byte is interpreted as a byte2 value of a CHAR2B with a byte1
value of zero.
GC components: alu-function, plane-mask, fill-style, font,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PolyText16
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
items: LISTofTEXTITEM16
where
TEXTITEM16: TEXTELT16 or FONT
TEXTELT16: [delta-x: INT8
string: STRING16]
Errors: Drawable, GContext, Match, Font
Just like PolyText8, except two-byte (or 16-bit) characters
are used. For fonts defined with linear indexing rather than
two-byte matrix indexing, the server will interpret each
CHAR2B as a 16-bit number that has been transmitted most
significant byte first (i.e., byte1 of the CHAR2B is taken
as the most significant byte).
ImageText8
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
string: STRING8
Errors: Drawable, GContext, Match
The x and y coordinates are relative to drawable's origin,
and specify the baseline starting position (the initial
character origin). The effect is to first fill a
destination rectangle with the background pixel defined in
gc, and then paint the text with the foreground pixel.
The upper left corner of the filled rectangle is at
[x + overall-left, y - font-ascent]
the width is
overall-right - overall-left
and the height is
font-ascent + font-descent
where overall-left, overall-right, font-ascent, and
as font-descent are would be returned by a QueryTextExtents
call using gc and string.
The alu-function and fill-style defined in gc are ignored for
this request; the effective alu-function is Copy and the
effective fill-style Solid.
For fonts defined with two-byte matrix indexing, each STRING8
byte is interpreted as a byte2 value of a CHAR2B with a byte1
value of zero.
GC components: plane-mask, foreground, background, font,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
ImageText16
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
string: STRING16
Errors: Drawable, GContext, Match
Just like ImageText8, except two-byte (or 16-bit) characters
are used. For fonts defined with linear indexing rather than
two-byte matrix indexing, the server will interpret each
CHAR2B as a 16-bit number that has been transmitted most
significant byte first (i.e., byte1 of the CHAR2B is taken as
the most significant byte).
CreateColormap
mid: COLORMAP
visual: VISUALID
window: WINDOW
alloc: {None, All}
Errors: IDChoice, Window, Value, Match, Alloc
Creates a colormap of the specified visual type for the
screen on which the window resides, and associates the
identifier mid with it. The visual type must be one
supported by the screen, and cannot be of class TrueColor
(else a Match error). The initial values of the colormap
entries are undefined for classes GrayScale, PseudoColor,
and DirectColor; for StaticGray, StaticColor, and
TrueColor, the entries will have defined values, but those
values are specific to the visual and are not defined by
the core protocol. For StaticGray, StaticColor, and
TrueColor, alloc must be specified as None (else a Match
error). For the other classes, if alloc is None, the
colormap initially has no allocated entries, and clients
can allocate entries. If alloc is All, then the entire
colormap is "allocated" writable, but entries cannot be
freed with FreeColors, and no relationships among entries
is defined; the client must understand whether the colormap
is GrayScale, PseudoColor, or DirectColor to know how to
store into entries.
FreeColormap
cmap: COLORMAP
Errors: Colormap
Deletes the association between the resource id and the
colormap. If the colormap is an installed map for a screen,
it is uninstalled (see UninstallColormap). If the colormap
is defined as the colormap for a window (via CreateWindow or
ChangeWindowAttributes), the colormap for the window is
changed to None, and a ColormapNotify event is generated.The
colors displayed for a window with a colormap of None are not
defined by the protocol.
Has no effect on a default colormap for a screen.
CopyColormapAndFree
mid, src-cmap: COLORMAP
Errors: Colormap, Alloc
Creates a colormap for the same screen as src-cmap, and
associates identifier mid with it. Moves all of the client's
existing allocations from src-cmap to the new colormap, and
frees those entries in src-cmap. Values in other entries in
the new colormap are undefined.
InstallColormap
cmap: COLORMAP
Errors: Colormap
Makes this colormap an installed map for its screen. All
windows associated with this colormap immediately display
with true colors. As a side-effect, previously installed
colormaps may be uninstalled, and other windows may display
with false colors. Which colormaps get uninstalled is
server dependent, except that it is guaranteed that the
M-1 most recently client-installed colormaps will not be
uninstalled, where M is the min-installed-maps specified
for the screen in the connection setup.
If cmap is not already an installed map, a ColormapNotify
event is generated on every window having cmap as an
attribute. If a colormap is uninstalled as a result of
the install, a ColormapNotify event is generated on every
window having that colormap as an attribute.
Initially only the default colormap for a screen is
installed.
UninstallColormap
cmap: COLORMAP
Errors: Colormap
If cmap is an installed map for its screen, one or more
colormaps are installed in its place; the choice is server
dependent, pexcept that if the screen's default colormap is
not installed and can be installed (without forcing other
colormaps out), then the default colormap is used.
If cmap is an installed map, a ColormapNotify event is
generated on every window having this colormap as an
attribute. If a colormap is installed as a result of the
uninstall, a ColormapNotify event is generated on every
window having that colormap as an attribute.
ListInstalledColormaps
window: WINDOW
=>
cmaps: LISTofCOLORMAP
Errors: Window
Returns a list of the currently installed colormaps for the
screen of the specified window.
AllocColor
cmap: COLORMAP
red, green, blue: CARD16
=>
pixel: CARD32
red, green, blue: CARD16
Errors: Colormap, Alloc
Allocates a read-only colormap entry corresponding to the
closest RGB values provided by the hardware. Returns the
pixel and the RGB values actually used.
AllocNamedColor
cmap: COLORMAP
name: STRING8
=>
pixel: CARD32
exact-red, exact-green, exact-blue: CARD16
screen-red, screen-green, screen-blue: CARD16
Errors: Colormap, Name, Alloc
Looks up the named color with respect to the screen
associated with the colormap, then does an AllocColor on
cmap. The name should use the ASCII encoding, and
upper/lower case does not matter. The exact RGB values
specify the "true" values for the color, and the screen
values specify the values actually used in the colormap.
AllocColorCells
cmap: COLORMAP
colors, planes: CARD16
contiguous: BOOL
=>
pixels, masks: LISTofCARD32
Errors: Colormap, Value, Alloc
The number of colors must be positive, the number of planes
non-negative. If C colors and P planes are requested, then C
pixels and P masks are returned. No mask will have any bits
in common with any other mask, or with any of the pixels. By
ORing together masks and pixels, C*(2^P) distinct pixels can
be produced; all of these are allocated writable by the
request. For GrayScale or PseudoColor, each mask will have
exactly one bit, and for DirectColor each will have exactly
three bits. If contiguous is True, then if all masks are
ORed together, a single contiguous set of bits will be formed
for GrayScale or PseudoColor, and three contiguous sets of
bits (one within each pixel subfield) for DirectColor. The
RGB values of the allocated entries are undefined.
AllocColorPlanes
cmap: COLORMAP
colors, reds, greens, blues: CARD16
contiguous: BOOL
=>
pixels: LISTofCARD32
red-mask, green-mask, blue-mask: CARD32
Errors; Colormap, Value, Alloc
The number of colors must be positive, the reds, greens, and
blues non-negative. If C colors, R reds, G greens, and B
blues are requested, then C pixels are returned, and the
masks have R, G, and B bits set respectively. If contiguous
is True, then each mask will have a contiguous set of bits.
No mask will have any bits in common with any other mask, or
with any of the pixels. For DirectColor, each mask will lie
within the corresponding pixel subfield. By ORing together
subsets of masks with pixels, C*(2^(R+G+B)) distinct pixels
can be produced; all of these are allocated by the request.
The initial RGB values of the allocated entries are
undefined. In the colormap there are only C*(2^R)
independent red entries, C*(2^G) independent green entries,
and C*(2^B) independent blue entries. This is true even for
PseudoColor. When the colormap entry for a pixel value is
changed using StoreColors or StoreNamedColor, the pixel is
decomposed according to the masks and the corresponding
independent entries are updated.
FreeColors
cmap: COLORMAP
pixels: LISTofCARD32
plane-mask: CARD32
Errors: Colormap, Access, Value
The plane-mask should not have any bits in common with any of
the pixels. The set of all pixels is produced by ORing
together subsets of plane-mask with the pixels. The request
frees all of these pixels. Note that freeing an individual
pixel obtained from AllocColorPlanes may not actually allow
it to be reused until all of its "related" pixels are also
freed.
All specified pixels that are allocated by the client in
cmap are freed, even if one or more pixels produce an error.
A Value error is generated if a specified pixel is not a
valid index into cmap, and an Access error is generated if a
specified pixel is not allocated by the client (i.e., is
unallocated or is only allocated by another client). If more
than one pixel is in error, which one is reported is
arbitrary.
StoreColors
cmap: COLORMAP
items: LISTofCOLORITEM
where
COLORITEM: [pixel: CARD32
do-red, do-green, do-blue: BOOL
red, green, blue: CARD16]
Errors: Colormap, Access, Value
Changes the colormap entries of the specified pixels. The
do-red, do-green, and do-blue fields indicate which
components should actually be changed. If the colormap is an
installed map for its screen, the changes are visible
immediately.
All specified pixels that are allocated writable in cmap (by
any client) are changed, even if one or more pixels produce
an error. A Value error is generated if a specified pixel is
not a valid index into cmap, and an Access error is generated
if a specified pixel is unallocated or is allocated
read-only. If more than one pixel is in error, which one is
reported is arbitrary.
StoreNamedColor
cmap: COLORMAP
pixel: CARD32
name: STRING8
do-red, do-green, do-blue: BOOL
Errors: Colormap, Name, Access, Value
Looks up the named color with respect to the screen
associated with cmap, then does a StoreColors in cmap. The