X Window System Protocol

X Consortium Standard

X Version 11, Release 6.8

Robert W. Scheifler
X Consortium, Inc.

X Window System is a trademark of The Open Group. Copyright © 1986, 1987, 1988, 1994, 2004 The Open Group Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘‘Software’’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED ‘‘AS IS’’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the Open Group shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the Open Group.

Acknowledgments

Acknowledgments

The primary contributers to the X11 protocol are:
Dave Carver (Digital HPW)
Branko Gerovac (Digital HPW)
Jim Gettys (MIT/Project Athena, Digital)
Phil Karlton (Digital WSL)
Scott McGregor (Digital SSG)
Ram Rao (Digital UEG)
David Rosenthal (Sun)
Dave Winchell (Digital UEG)
The implementors of initial server who provided useful
input are:

Susan Angebranndt (Digital)
Raymond Drewry (Digital)
Todd Newman (Digital)
The invited reviewers who provided useful input are:
Andrew Cherenson (Berkeley)
Burns Fisher (Digital)
Dan Garfinkel (HP)
Leo Hourvitz (Next)
Brock Krizan (HP)
David Laidlaw (Stellar)
Dave Mellinger (Interleaf)
Ron Newman (MIT)
John Ousterhout (Berkeley)
Andrew Palay (ITC CMU)
Ralph Swick (MIT)
Craig Taylor (Sun)
Jeffery Vroom (Stellar)
Thanks go to Al Mento of Digital’s UEG Documentation Group for
formatting this document.
This document does not attempt to provide the rationale or pragmatics required
to fully understand the protocol or to place it in perspective within a
complete system.
The protocol contains many management mechanisms that are not intended for
normal applications.
Not all mechanisms are needed to build a particular user interface.
It is important to keep in mind that the protocol is intended to
provide mechanism, not policy.
Robert W. Scheifler
X Consortium, Inc.

Protocol Formats
Protocol Formats
Request Format
Every request contains an 8-bit major opcode and a 16-bit length field
expressed in units of four bytes.
Every request consists of four bytes of a header
(containing the major opcode, the length field, and a data byte)
followed by zero or more additional bytes of data.
The length field defines the total length of the request, including the header.
The length field in a request must equal the minimum length required to contain
the request.
If the specified length is smaller or larger than the required length,
an error is generated.
Unused bytes in a request are not required to be zero.
Major opcodes 128 through 255 are reserved for extensions.
Extensions are intended to contain multiple requests,
so extension requests typically have an additional minor opcode encoded
in the second data byte in the request header.
However, the placement and interpretation of this minor opcode and of all
other fields in extension requests are not defined by the core protocol.
Every request on a given connection is implicitly assigned a sequence number,
starting with one, that is used in replies, errors, and events.
Reply Format
Every reply contains a 32-bit length field expressed in units of four bytes.
Every reply consists of 32 bytes followed by zero or more additional bytes of
data, as specified in the length field.
Unused bytes within a reply are not guaranteed to be zero.
Every reply also contains the least significant 16 bits of the sequence number
of the corresponding request.
Error Format
Error reports are 32 bytes long.
Every error includes an 8-bit error code.
Error codes 128 through 255 are reserved for extensions.
Every error also includes the major and minor opcodes of the failed request
and the least significant 16 bits of the sequence number of the request.
For the following errors (see section 4),
the failing resource ID is also returned:
Colormap,
Cursor,
Drawable,
Font,
GContext,
IDChoice,
Pixmap,
and
Window.
For
Atom
errors, the failing atom is returned.
For
Value
errors, the failing value is returned.
Other core errors return no additional data.
Unused bytes within an error are not guaranteed to be zero.
Event Format
Events are 32 bytes long.
Unused bytes within an event are not guaranteed to be zero.
Every event contains an 8-bit type code.
The most significant bit in this code is set if the event was generated from a
SendEvent
request.
Event codes 64 through 127 are reserved for extensions, although the core
protocol does not define a mechanism for selecting interest in such events.
Every core event (with the exception of
KeymapNotify)
also contains the least significant 16 bits of the sequence number of the last
request issued by the client that was (or is currently being) processed by
the server.
Syntactic Conventions
Syntactic Conventions
The rest of this document uses the following syntactic conventions.
The syntax {...} encloses a set of alternatives.
The syntax [...] encloses a set of structure components.
In general, TYPEs are in uppercase and
AlternativeValues
are capitalized.
Requests in section 9 are described in the following format:

Common Types
HTML-IMAGE.if 0=1 .nr d. 499-499-1 _____________________________________________________________________________________________
Name Value _____________________________________________________________________________________________
LISTofFOO

A type name of the form LISTofFOO means a counted list of elements of type
FOO.
The size of the length field may vary (it is not necessarily the same
size as a FOO), and in some cases, it may be implicit.
It is fully specified in Appendix B.
Except where explicitly noted,
zero-length lists are legal.

BITMASK
LISTofVALUE

The types BITMASK and LISTofVALUE are somewhat special.
Various requests contain arguments of the form:
value-mask: BITMASK
value-list: LISTofVALUE
These are used to allow the client to specify a subset of a heterogeneous
collection of optional arguments.
The value-mask specifies which arguments are to be provided;
each such argument is assigned a unique bit position.
The representation of the BITMASK will typically contain more bits than
there are defined arguments.
The unused bits in the value-mask must be zero (or the server generates a
Value
error).
The value-list contains one value for each bit set to 1 in the mask,
from least significant to most significant bit in the mask.
Each value is represented with four bytes,
but the actual value occupies only the least significant bytes as required.
The values of the unused bytes do not matter.

OR

A type of the form ‘‘T1 or ... or Tn’’ means the union of the indicated types.
A single-element type is given as the element without enclosing braces.

WINDOW 32-bit value (top three bits guaranteed to be zero)
PIXMAP 32-bit value (top three bits guaranteed to be zero)
CURSOR 32-bit value (top three bits guaranteed to be zero)
FONT 32-bit value (top three bits guaranteed to be zero)
GCONTEXT 32-bit value (top three bits guaranteed to be zero)
COLORMAP 32-bit value (top three bits guaranteed to be zero)
DRAWABLE WINDOW or PIXMAP
FONTABLE FONT or GCONTEXT
ATOM 32-bit value (top three bits guaranteed to be zero)
VISUALID 32-bit value (top three bits guaranteed to be zero)
VALUE 32-bit quantity (used only in LISTofVALUE)
BYTE 8-bit value
INT8 8-bit signed integer
INT16 16-bit signed integer
INT32 32-bit signed integer
CARD8 8-bit unsigned integer
CARD16 16-bit unsigned integer
CARD32 32-bit unsigned integer
TIMESTAMP CARD32
BITGRAVITY

{Forget,
Static,
NorthWest,
North,
NorthEast,
West,
Center, 
East,
SouthWest,
South,
SouthEast}

WINGRAVITY

{Unmap,
Static,
NorthWest,
North,
NorthEast,
West,
Center, 
East,
SouthWest,
South,
SouthEast}

BOOL

{True,
False}

EVENT

{KeyPress,
KeyRelease,
OwnerGrabButton,
ButtonPress, 
ButtonRelease,
EnterWindow,
LeaveWindow,
PointerMotion, 
PointerMotionHint,
Button1Motion,
Button2Motion, 
Button3Motion,
Button4Motion,
Button5Motion,
ButtonMotion, 
Exposure,
VisibilityChange,
StructureNotify,
ResizeRedirect, 
SubstructureNotify,
SubstructureRedirect,
FocusChange, 
PropertyChange,
ColormapChange,
KeymapState}

POINTEREVENT

{ButtonPress,
ButtonRelease,
EnterWindow,
LeaveWindow, 
PointerMotion,
PointerMotionHint,
Button1Motion, 
Button2Motion,
Button3Motion,
Button4Motion,
Button5Motion, 
ButtonMotion,
KeymapState}

DEVICEEVENT

{KeyPress,
KeyRelease,
ButtonPress,
ButtonRelease, 
PointerMotion,
Button1Motion,
Button2Motion,
Button3Motion, 
Button4Motion,
Button5Motion,
ButtonMotion}

KEYSYM 32-bit value (top three bits guaranteed to be zero)
KEYCODE CARD8
BUTTON CARD8
KEYMASK

{Shift,
Lock,
Control,
Mod1,
Mod2,
Mod3,
Mod4,
Mod5}

BUTMASK

{Button1,
Button2,
Button3,
Button4,
Button5}

KEYBUTMASK KEYMASK or BUTMASK
STRING8 LISTofCARD8
STRING16 LISTofCHAR2B
CHAR2B [byte1, byte2: CARD8]
POINT [x, y: INT16]
RECTANGLE

[x, y: INT16, 
width, height: CARD16]

ARC

[x, y: INT16, 
width, height: CARD16, 
angle1, angle2: INT16]

HOST

[family:
{Internet,
InternetV6,
ServerInterpreted,
DECnet,
Chaos} 
address: LISTofBYTE]

HTML-IMAGE-END.if 0=0 .nr c. 1565-0-274
The [x,y] coordinates of a RECTANGLE specify the upper-left corner.
The primary interpretation of large characters in a STRING16 is that they
are composed of two bytes used to index a two-dimensional matrix,
hence, the use of CHAR2B rather than CARD16.
This corresponds to the JIS/ISO method of indexing 2-byte characters.
It is expected that most large fonts will be defined with 2-byte
matrix indexing.
For large fonts constructed with linear indexing,
a CHAR2B can be interpreted as a 16-bit number by treating byte1 as
the most significant byte.
This means that clients should always transmit such
16-bit character values most significant byte first, as the server will never
byte-swap CHAR2B quantities.
The length, format, and interpretation of a HOST address are specific to the
family (see
ChangeHosts
request).
Errors
Errors
In general, when a request terminates with an error,
the request has no side effects (that is, there is no partial execution).
The only requests for which this is not true are
ChangeWindowAttributes,
ChangeGC,
PolyText8,
PolyText16,
FreeColors,
StoreColors,
and
ChangeKeyboardControl.
The following error codes result from various requests as follows:
HTML-IMAGE.if 0=1 .nr d. 1606-1606-1 ________________________________________________________________________________________________
Error Description ________________________________________________________________________________________________
Access

An attempt is made to grab a key/button combination already grabbed by another
client.
An attempt is made to free a colormap entry not allocated by the client
or to free an entry in a colormap that was created with all entries writable.
An attempt is made to store into a read-only or an unallocated colormap entry.
An attempt is made to modify the access control list from other than the local
host (or otherwise authorized client).
An attempt is made to select an event type that only one client can
select at a time when another client has already selected it.

Alloc

The server failed to allocate the requested resource.
Note that the explicit listing of
Alloc
errors in request only covers allocation errors at a very coarse level
and is not intended to cover all cases
of a server running out of allocation space in the middle of service.
The semantics when a server runs out of allocation space are left unspecified,
but a server may generate an
Alloc
error on any request for this reason,
and clients should be prepared to receive such errors and handle
or discard them.

Atom

A value for an ATOM argument does not name a defined ATOM.

Colormap

A value for a COLORMAP argument does not name a defined COLORMAP.

Cursor

A value for a CURSOR argument does not name a defined CURSOR.

Drawable

A value for a DRAWABLE argument does not name a defined WINDOW or
PIXMAP.

Font

A value for a FONT argument does not name a defined FONT.
A value for a FONTABLE argument does not name a defined FONT or a
defined GCONTEXT.

GContext

A value for a GCONTEXT argument does not name a defined GCONTEXT.

IDChoice

The value chosen for a resource identifier either is not included
in the range assigned to the client or is already in use.

Implementation

The server does not implement some aspect of the request.
A server that generates this error for a core request is deficient.
As such, this error is not listed for any of the requests,
but clients should be prepared to receive such errors
and handle or discard them.

Length

The length of a request is shorter or longer than that required
to minimally contain the arguments.
The length of a request exceeds the maximum length accepted by the
server.

Match

An
InputOnly
window is used as a DRAWABLE.
In a graphics request, the GCONTEXT argument does not have the same
root and depth as the destination DRAWABLE argument.
Some argument (or pair of arguments) has the correct type and range,
but it fails to match in some other way required by the request.

Name

A font or color of the specified name does not exist.

Pixmap

A value for a PIXMAP argument does not name a defined PIXMAP.

Request

The major or minor opcode does not specify a valid request.

Value

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 typically can generate
this error (due to the encoding).

Window

A value for a WINDOW argument does not name a defined WINDOW. ________________________________________________________________________________________________

HTML-IMAGE-END.if 0=0 .nr c. 2845-0-179

Note

The
Atom,
Colormap,
Cursor,
Drawable,
Font,
GContext,
Pixmap,
and
Window
errors are also used when the argument type is extended by union with a
set of fixed alternatives, for example, <WINDOW or
PointerRoot
or
None>.

Keyboards
Keyboards
A KEYCODE represents a physical (or logical) key.
Keycodes lie in the inclusive range [8,255].
A keycode value carries no intrinsic information,
although server implementors may attempt to encode geometry information
(for example, matrix) to be interpreted in a server-dependent fashion.
The mapping between keys and keycodes cannot be changed using the
protocol.
A KEYSYM is an encoding of a symbol on the cap of a key.
The set of defined KEYSYMs include the character sets Latin-1, Latin-2,
Latin-3, Latin-4, Kana, Arabic, Cyrillic, Greek, Tech, Special, Publish, APL,
Hebrew, Thai, and Korean as well as a set of symbols common on keyboards
(Return, Help, Tab,
and so on).
KEYSYMs with the most significant bit (of the 29 bits) set are reserved
as vendor-specific.
A list of KEYSYMs is associated with each KEYCODE.
The list is intended to convey the set of symbols on the corresponding key.
If the list (ignoring trailing
NoSymbol
entries) is a single KEYSYM ‘‘K’’,
then the list is treated as if it were
the list ‘‘K NoSymbol K NoSymbol’’.
If the list (ignoring trailing NoSymbol entries) is a pair of KEYSYMs
‘‘K1 K2’’, then the list is treated as if it were the list
‘‘K1 K2 K1 K2’’.
If the list (ignoring trailing
NoSymbol
entries) is
a triple of KEYSYMs ‘‘K1 K2 K3’’,
then the list is treated as if it were the list ‘‘K1 K2 K3 NoSymbol’’.
When an explicit ‘‘void’’ element is desired in the list,
the value
VoidSymbol
can be used.
The first four elements of the list are split into two groups of KEYSYMs.
Group 1 contains the first and second KEYSYMs, Group 2 contains the third and
fourth KEYSYMs.
Within each group,
if the second element of the group is
NoSymbol,
then the group should be treated as if the second element were the
same as the first element, except when the first element is an alphabetic
KEYSYM ‘‘K’’ for which both lowercase and uppercase forms are defined.
In that case, the group should be treated as if the first element were the
lowercase form of ‘‘K’’ and the second element were the uppercase form
of ‘‘K’’.
The standard rules for obtaining a KEYSYM from a
KeyPress
event make use of only the Group 1 and Group 2 KEYSYMs; no interpretation of
other KEYSYMs in the list is defined. The modifier state determines which
group to use. Switching between groups is controlled by the KEYSYM named
MODE SWITCH, by attaching that KEYSYM to some KEYCODE and attaching that
KEYCODE to any one of the modifiers
Mod1
through
Mod5.
This modifier is
called the ‘‘group modifier’’. For any KEYCODE, Group 1 is used when the
group modifier is off, and Group 2 is used when the group modifier is on.
The
Lock
modifier is interpreted as CapsLock when the KEYSYM named CAPS
LOCK is attached to some KEYCODE and that KEYCODE is attached to the
Lock
modifier. The
Lock
modifier is interpreted as ShiftLock when the KEYSYM
named SHIFT LOCK is attached to some KEYCODE and that KEYCODE is attached
to the
Lock
modifier. If the
Lock
modifier could be interpreted as both
CapsLock and ShiftLock, the CapsLock interpretation is used.
The operation of ‘‘keypad’’ keys is controlled by the KEYSYM named NUM LOCK,
by attaching that KEYSYM to some KEYCODE and attaching that KEYCODE to any
one of the modifiers
Mod1
through
Mod5.
This modifier is called the
‘‘numlock modifier’’. The standard KEYSYMs with the prefix KEYPAD in their
name are called ‘‘keypad’’ KEYSYMs; these are KEYSYMS with numeric value in
the hexadecimal range #xFF80 to #xFFBD inclusive. In addition,
vendor-specific KEYSYMS in the hexadecimal range #x11000000 to #x1100FFFF
are also keypad KEYSYMs.
Within a group, the choice of KEYSYM is determined by applying the first
rule that is satisfied from the following list:
The numlock modifier is on and the second KEYSYM is a keypad KEYSYM. In
this case, if the
Shift
modifier is on, or if the
Lock
modifier is on and
is interpreted as ShiftLock, then the first KEYSYM is used; otherwise, the
second KEYSYM is used.
The
Shift
and
Lock
modifiers are both off. In this case, the first
KEYSYM is used.
The
Shift
modifier is off, and the
Lock
modifier is on and is
interpreted as CapsLock. In this case, the first KEYSYM is used, but if
that KEYSYM is lowercase alphabetic, then the corresponding uppercase
KEYSYM is used instead.
The
Shift
modifier is on, and the
Lock
modifier is on and is interpreted
as CapsLock. In this case, the second KEYSYM is used, but if that KEYSYM
is lowercase alphabetic, then the corresponding uppercase KEYSYM is used
instead.
The
Shift
modifier is on, or the
Lock
modifier is on and is interpreted
as ShiftLock, or both. In this case, the second KEYSYM is used.
The mapping between KEYCODEs and KEYSYMs is not used directly by the server;
it is merely stored for reading and writing by clients.
Pointers
Pointers
Buttons are always numbered starting with one.
Predefined Atoms
Predefined Atoms
Predefined atoms are not strictly necessary and may not be useful in all
environments, but they will eliminate many
InternAtom
requests in most applications.
Note that they are predefined only in the sense of having numeric values,
not in the sense of having required semantics.
The core protocol imposes no semantics on these names,
but semantics are specified in other X Window System standards,
such as the Inter-Client Communication Conventions Manual
and the X Logical Font Description Conventions.
The following names have predefined atom values.
Note that uppercase and lowercase matter.
HTML-IMAGE.if 0=1 .nr d. 3035-3035-1
ARC ITALIC_ANGLE STRING
ATOM MAX_SPACE SUBSCRIPT_X
BITMAP MIN_SPACE SUBSCRIPT_Y
CAP_HEIGHT NORM_SPACE SUPERSCRIPT_X
CARDINAL NOTICE SUPERSCRIPT_Y
COLORMAP PIXMAP UNDERLINE_POSITION
COPYRIGHT POINT UNDERLINE_THICKNESS
CURSOR POINT_SIZE VISUALID
CUT_BUFFER0 PRIMARY WEIGHT
CUT_BUFFER1 QUAD_WIDTH WINDOW
CUT_BUFFER2 RECTANGLE WM_CLASS
CUT_BUFFER3 RESOLUTION WM_CLIENT_MACHINE
CUT_BUFFER4 RESOURCE_MANAGER WM_COMMAND
CUT_BUFFER5 RGB_BEST_MAP WM_HINTS
CUT_BUFFER6 RGB_BLUE_MAP WM_ICON_NAME
CUT_BUFFER7 RGB_COLOR_MAP WM_ICON_SIZE
DRAWABLE RGB_DEFAULT_MAP WM_NAME
END_SPACE RGB_GRAY_MAP WM_NORMAL_HINTS
FAMILY_NAME RGB_GREEN_MAP WM_SIZE_HINTS
FONT RGB_RED_MAP WM_TRANSIENT_FOR
FONT_NAME SECONDARY WM_ZOOM_HINTS
FULL_NAME STRIKEOUT_ASCENT X_HEIGHT
INTEGER STRIKEOUT_DESCENT
HTML-IMAGE-END.if 0=0 .nr c. 3323-0-25
To avoid conflicts with possible future names for which semantics might be
imposed (either at the protocol level or in terms of higher level user
interface models),
names beginning with an underscore should be used for atoms
that are private to a particular vendor or organization.
To guarantee no conflicts between vendors and organizations,
additional prefixes need to be used.
However, the protocol does not define the mechanism for choosing such prefixes.
For names private to a single application or end user but stored in globally
accessible locations,
it is suggested that two leading underscores be used to avoid conflicts with
other names.
Connection Setup
Connection Setup
For remote clients,
the X protocol can be built on top of any reliable byte stream.
Connection Initiation
The client must send an initial byte of data to identify the byte order to be
employed.
The value of the byte must be octal 102 or 154.
The value 102 (ASCII uppercase B) means values are transmitted most significant
byte first, and value 154 (ASCII lowercase l) means values are transmitted
least significant byte first.
Except where explicitly noted in the protocol,
all 16-bit and 32-bit quantities sent by the client must be transmitted with
this byte order,
and all 16-bit and 32-bit quantities returned by the server will be transmitted
with this byte order.
Following the byte-order byte,
the client sends the following information at connection setup:
protocol-major-version: CARD16
protocol-minor-version: CARD16
authorization-protocol-name: STRING8
authorization-protocol-data: STRING8
The version numbers indicate what version of the protocol the client
expects the server to implement.
The authorization name indicates what authorization (and authentication)
protocol the client
expects the server to use, and the data is specific to that protocol.
Specification of valid authorization mechanisms is not part of the core
X protocol.
A server that does not implement the protocol the client expects
or that only implements the host-based mechanism may simply ignore this
information.
If both name and data strings are empty,
this is to be interpreted as ‘‘no explicit authorization.’’
Server Response
The client receives the following information at connection setup:
success:
{Failed,
Success,
Authenticate}
The client receives the following additional data if the returned success
value is
Failed,
and the connection is not successfully established:
protocol-major-version: CARD16
protocol-minor-version: CARD16
reason: STRING8
The client receives the following additional data if the returned success
value is
Authenticate,
and further authentication negotiation is required:
reason: STRING8
The contents of the reason string are specific to the authorization
protocol in use. The semantics of this authentication negotiation are
not constrained, except that the negotiation must eventually terminate
with a reply from the server containing a success value of
Failed
or
Success.
The client receives the following additional data if the returned success
value is
Success,
and the connection is successfully established:
protocol-major-version: CARD16
protocol-minor-version: CARD16
vendor: STRING8
release-number: CARD32
resource-id-base, resource-id-mask: CARD32
image-byte-order:
{LSBFirst,
MSBFirst}
bitmap-scanline-unit: {8, 16, 32}
bitmap-scanline-pad: {8, 16, 32}
bitmap-bit-order:
{LeastSignificant,
MostSignificant}
pixmap-formats: LISTofFORMAT
roots: LISTofSCREEN
motion-buffer-size: CARD32
maximum-request-length: CARD16
min-keycode, max-keycode: KEYCODE
where:
HTML-IMAGE.if 0=1 .nr d. 3459-3459-1

FORMAT:

[depth: CARD8, 
bits-per-pixel: {1, 4, 8, 16, 24, 32} 
scanline-pad: {8, 16, 32}]

SCREEN:

[root: WINDOW 
width-in-pixels, height-in-pixels: CARD16 
width-in-millimeters, height-in-millimeters: CARD16 
allowed-depths: LISTofDEPTH 
root-depth: CARD8 
root-visual: VISUALID 
default-colormap: COLORMAP 
white-pixel, black-pixel: CARD32 
min-installed-maps, max-installed-maps: CARD16 
backing-stores:
{Never,
WhenMapped,
Always} 
save-unders: BOOL 
current-input-masks: SETofEVENT]

DEPTH:

[depth: CARD8 
visuals: LISTofVISUALTYPE]

VISUALTYPE:

[visual-id: VISUALID 
class:
{StaticGray,
StaticColor,
TrueColor,
GrayScale,          
PseudoColor,
DirectColor} 
red-mask, green-mask, blue-mask: CARD32 
bits-per-rgb-value: CARD8 
colormap-entries: CARD16]

HTML-IMAGE-END.if 0=0 .nr c. 3821-0-72
Server Information
The information that is global to the server is:
The protocol version numbers are an escape hatch in case future revisions of
the protocol are necessary.
In general,
the major version would increment for incompatible changes,
and the minor version would increment for small upward compatible changes.
Barring changes,
the major version will be 11, and the minor version will be 0.
The protocol version numbers returned indicate the protocol the server
actually supports.
This might not equal the version sent by the client.
The server can (but need not) refuse connections from clients that offer a
different version than the server supports.
A server can (but need not) support more than one version simultaneously.
The vendor string gives some identification of the owner of the server
implementation.
The vendor controls the semantics of the release number.
The resource-id-mask contains a single contiguous set of bits (at least 18).
The client allocates resource IDs for types WINDOW, PIXMAP,
CURSOR, FONT, GCONTEXT, and COLORMAP by choosing a value with only
some subset of these bits set and ORing it with resource-id-base.
Only values constructed in this way can be used to name newly created
resources over this connection.
Resource IDs never have the top three bits set.
The client is not restricted to linear or contiguous allocation
of resource IDs.
Once an ID has been freed,
it can be reused.
An ID must be unique with respect to the IDs of all other resources,
not just other resources of the same type.
However, note that the value spaces of resource identifiers,
atoms, visualids, and keysyms are distinguished by context, and
as such, are not required to be disjoint; for example, a given numeric value
might be both a valid window ID, a valid atom, and a valid keysym.
Although the server is in general responsible for byte-swapping data to
match the client,
images are always transmitted and received in formats (including byte order)
specified by the server.
The byte order for images is given by image-byte-order and applies to each
scanline unit in XY format (bitmap format) and to each pixel value in Z format.
A bitmap is represented in scanline order.
Each scanline is padded to a multiple of bits as given by bitmap-scanline-pad.
The pad bits are of arbitrary value.
The scanline is quantized in multiples of bits as given by bitmap-scanline-unit.
The bitmap-scanline-unit is always less than or equal to the
bitmap-scanline-pad.
Within each unit,
the leftmost bit in the bitmap is either the least significant
or most significant bit in the unit, as given by bitmap-bit-order.
If a pixmap is represented in XY format,
each plane is represented as a bitmap, and the planes appear from
most significant to least significant in bit order with no padding
between planes.
Pixmap-formats contains one entry for each depth value.
The entry describes the Z format used to represent images of that depth.
An entry for a depth is included if any screen supports that depth,
and all screens supporting that depth must support only that Z format for that
depth.
In Z format,
the pixels are in scanline order, left to right within a scanline.
The number of bits used to hold each pixel is given by bits-per-pixel.
Bits-per-pixel may be larger than strictly required by the depth,
in which case the least significant bits are used to hold
the pixmap data, and the values of the unused high-order bits are
undefined.
When the bits-per-pixel is 4,
the order of nibbles in the byte is the same as the image byte-order.
When the bits-per-pixel is 1,
the format is identical for bitmap format.
Each scanline is padded to a multiple of bits as given by scanline-pad.
When bits-per-pixel is 1,
this will be identical to bitmap-scanline-pad.
How a pointing device roams the screens is up to the server
implementation and is transparent to the protocol.
No geometry is defined among screens.
The server may retain the recent history of pointer motion and do so to a
finer granularity than is reported by
MotionNotify
events.
The
GetMotionEvents
request makes such history available.
The motion-buffer-size gives the approximate maximum number
of elements in the history buffer.
Maximum-request-length specifies the maximum length of a request
accepted by the server, in 4-byte units.
That is, length is the maximum value that can appear in the length field of a
request.
Requests larger than this maximum generate a
Length
error,
and the server will read and simply discard the entire request.
Maximum-request-length will always be at least 4096
(that is, requests of length up to and including 16384 bytes
will be accepted by all servers).
Min-keycode and max-keycode specify the smallest and largest keycode
values transmitted by the server.
Min-keycode is never less than 8,
and max-keycode is never greater than 255.
Not all keycodes in this range are required to have corresponding keys.
Screen Information
The information that applies per screen is:
The allowed-depths specifies what pixmap and window depths are supported.
Pixmaps are supported for each depth listed,
and windows of that depth are supported if at least one visual type is listed
for the depth.
A pixmap depth of one is always supported and listed,
but windows of depth one might not be supported.
A depth of zero is never listed,
but zero-depth
InputOnly
windows are always supported.
Root-depth and root-visual specify the depth and visual type of the
root window.
Width-in-pixels and height-in-pixels specify the size of
the root window (which cannot be changed).
The class of the root window is always
InputOutput.
Width-in-millimeters and height-in-millimeters can be used to determine the
physical size and the aspect ratio.
The default-colormap is the one initially associated with the root window.
Clients with minimal color requirements creating windows of
the same depth as the root may want to allocate from this map by
default.
Black-pixel and white-pixel can be used in implementing a monochrome
application.
These pixel values are for permanently allocated entries in the
default-colormap.
The actual RGB values may be settable on some screens
and, in any case, may not actually be black and white.
The names are intended to convey the expected relative intensity of the colors.
The border of the root window is initially a pixmap filled with the black-pixel.
The initial background of the root window is a pixmap filled with some
unspecified two-color pattern using black-pixel and white-pixel.
Min-installed-maps specifies the number of maps that can be guaranteed
to be installed simultaneously (with
InstallColormap),
regardless of the number of entries allocated in each map.
Max-installed-maps specifies the maximum number of maps that might possibly be
installed simultaneously, depending on their allocations.
Multiple static-visual colormaps with identical contents but differing in
resource ID should be considered as a single map for the purposes of this
number.
For the typical case of a single hardware colormap, both values will be 1.
Backing-stores indicates when the server supports backing stores for
this screen, although it may be storage limited in the number of
windows it can support at once.
If save-unders is
True,
the server can support the save-under mode in
CreateWindow
and
ChangeWindowAttributes,
although again it may be storage limited.
The current-input-events is what
GetWindowAttributes
would return for the all-event-masks for the root window.
Visual Information
The information that applies per visual-type is:
A given visual type might be listed for more than one depth or for
more than one screen.
For
PseudoColor,
a pixel value indexes a colormap to produce independent RGB values;
the RGB values can be changed dynamically.
GrayScale
is treated in the same way as
PseudoColor
except which primary drives the screen is undefined;
thus, the client should always store the
same value for red, green, and blue in colormaps.
For
DirectColor,
a pixel value is decomposed into separate RGB subfields,
and each subfield separately indexes the colormap for the corresponding value.
The RGB values can be changed dynamically.
TrueColor
is treated in the same way as
DirectColor
except the colormap has predefined read-only RGB values.
These values are server-dependent but provide linear or near-linear
increasing ramps in each primary.
StaticColor
is treated in the same way as
PseudoColor
except the colormap has predefined read-only RGB values,
which are server-dependent.
StaticGray
is treated in the same way as
StaticColor
except the red, green, and blue values are equal for any
single pixel value, resulting in shades of gray.
StaticGray
with a two-entry colormap can be thought of as monochrome.
The red-mask, green-mask, and blue-mask are only defined for
DirectColor
and
TrueColor.
Each has one contiguous set of bits set to 1 with no intersections.
Usually each mask has the same number of bits set to 1.
The bits-per-rgb-value specifies the log base 2 of the number of
distinct color intensity values (individually) of red, green, and blue.
This number need not bear any relation to the number of colormap entries.
Actual RGB values are always passed in the protocol within a
16-bit spectrum, with 0 being minimum intensity and 65535 being the
maximum intensity.
On hardware that provides a linear zero-based intensity ramp,
the following relationship exists:
hw-intensity = protocol-intensity / (65536 / total-hw-intensities)
Colormap entries are indexed from 0.
The colormap-entries defines the number of available colormap entries in a
newly created colormap.
For
DirectColor
and
TrueColor,
this will usually be 2 to the power of the maximum number of bits set to 1 in
red-mask, green-mask, and blue-mask.
Requests
Requests
HTML-IMAGE.nr 99 11