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:
RequestName |
arg1: type1 |
... |
|
argN: typeN |
|
→ |
result1: type1 |
... |
|
resultM: typeM |
|
Errors: kind1, ..., kindK |
|
Description. |
|
EventName |
value1: type1 |
... |
|
valueN: typeN |
|
Description. |
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