Beruflich Dokumente
Kultur Dokumente
Version 1.4.0
2012-07-03
Jim Gettys
Jim.Gettys@hp.com
Cambridge Research Laboratory
HP Labs
Hewlett Packard Company
Keith Packard
keith.packard@intel.com
Open Source Technology Center
Intel Corporation
1. Introduction
The X Resize, Rotate and Reflect Extension, called RandR for short,
brings the ability to resize, rotate and reflect the root window of a
screen. It is based on the X Resize and Rotate Extension as specified
in the Proceedings of the 2001 Usenix Technical Conference [RANDR].
RandR as implemented and integrated into the X server differs in
one substantial fashion from the design discussed in that paper: that
is, RandR 1.0 does not implement the depth switching described in that
document, and the support described for that in the protocol in that
document and in the implementation has been removed from the
protocol described here, as it has been overtaken by events.
These events include:
Modern toolkits (in this case, GTK+ 2.x) have progressed to the point
of implementing migration between screens of arbitrary depths
The continued advance of Moore's law has made limited amounts of VRAM
less of an issue, reducing the pressure to implement depth switching
on laptops or desktop systems
The continued decline of legacy toolkits whose design would have
required depth switching to support migration
The lack of depth switching implementation experience in the
intervening time, due to events beyond our control
Additionally, the requirement to support depth switching might
complicate other re-engineering of the device independent part of the
X server that is currently being contemplated.
Rather than further delaying RandR's widespread deployment for a feature
long wanted by the community (resizing of screens, particularly on laptops),
or the deployment of a protocol design that might be flawed due to lack of
implementation experience, we decided to remove depth switching from the
protocol. It may be implemented at a later time if resources and
interests permit as a revision to the protocol described here, which will
remain a stable base for applications. The protocol described here has been
implemented in the main X.org server, and more fully in the hw/kdrive
implementation in the distribution, which fully implements resizing,
rotation and reflection.
1.2 Introduction to version 1.2 of the extension
One of the significant limitations found in version 1.1 of the RandR
protocol was the inability to deal with the Xinerama model where multiple
monitors display portions of a common underlying screen. In this environment,
zero or more video outputs are associated with each CRT controller which
defines both a set of video timings and a 'viewport' within the larger
screen. This viewport is independent of the overall size of the screen, and
may be located anywhere within the screen.
The effect is to decouple the reported size of the screen from the size
presented by each video output, and to permit multiple outputs to present
information for a single screen.
To extend RandR for this model, we separate out the output, CRTC and screen
configuration information and permit them to be configured separately. For
compatibility with the 1.1 version of the protocol, we make the 1.1 requests
simultaneously affect both the screen and the (presumably sole) CRTC and
output. The set of available outputs are presented with UTF-8 encoded names
and may be connected to CRTCs as permitted by the underlying hardware. CRTC
configuration is now done with full mode information instead of just size
and refresh rate, and these modes have names. These names also use UTF-8
encoding. New modes may also be added by the user.
Additional requests and events are provided for this new functionality.
A
B
In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1
is connected to two outputs, A and B. CRTC2 is connected to output C.
Outputs A and B will present exactly the same region of the screen using
the same mode line. Output C will present a different (larger) region of
the screen using a different mode line.
RandR provides information about each available CRTC and output; the
connection between CRTC and output is under application control, although
the hardware will probably impose restrictions on the possible
configurations. The protocol doesn't try to describe these restrictions,
instead it provides a mechanism to find out what combinations are supported.
1.3 Introduction to version 1.3 of the extension
Version 1.3 builds on the changes made with version 1.2 and adds some new
capabilities without fundmentally changing the extension again. The
following features are added in this version:
Projective Transforms. The implementation work for general rotation
support made it trivial to add full projective transformations. These
can be used to scale the screen up/down as well as perform projector
keystone correct or other effects.
Panning. It was removed with RandR 1.2 because the old semantics didn't
fit any longer. With RandR 1.3 panning can be specified per crtc.
3. Data Types
The subpixel order is shared with the Render extension, and is documented
there. The only datatype defined is the screen size, defined in the normal
(0 degree) orientation.
4. Errors
Errors are sent using core X error reports.
Output
CRTC
Mode
5. Protocol Types
RRCONFIGSTATUS { Success
InvalidConfigTime
InvalidTime
Failed }
A value of type RRCONFIGSTATUS returned when manipulating the output
configuration or querying information from the server that has some
time-dependency.
InvalidConfigTime indicates that the supplied configuration
timestamp does not match the current X server configuration
timestamp. Usually this means that the output configuration has
changed since the timestamp was received by the application.
InvalidTime indicates that the supplied output reconfiguration time
is earlier than the most recent output reconfiguration request.
Generally this indicates that another application has reconfigured
the output using a later timestamp.
Failed is returned whenever the operation is unsuccessful for some
other reason. This generally indicates that the requested output
configuration is unsupported by the hardware. The goal is to make
these limitations expressed by the protocol, but when that isn't
possible it is correct to return this error value. If, as a
implentor, you find this error code required, please submit the
hardware constraints that exist so that a future version of the
extension can correctly capture the configuration constraints in
your system.
ROTATION { Rotate_0
Rotate_90
Rotate_180
Rotate_270
Reflect_X
Reflect_Y }
These values are used both to indicate a set of allowed rotations
and reflections as well as to indicate a specific rotation and
reflection combination.
RRSELECTMASK { RRScreenChangeNotifyMask
RRCrtcChangeNotifyMask (New in version 1.2)
RROutputChangeNotifyMask (New in version 1.2)
RROutputPropertyNotifyMask (New in version 1.2)
RRProviderChangeNotifyMask (New in version 1.4)
RRProviderPropertyNotifyMask (New in version 1.4)
RRResourceChangeNotifyMask (New in version 1.4) }
SIZEID { CARD16 }
MODE { XID or None }
CRTC { XID }
OUTPUT { XID }
CONNECTION { Connected, Disconnected, UnknownConnection }
This value provides an indication of whether an output is actually
connected to a monitor or other presentation device.
SUBPIXELORDER { SubPixelUnknown
SubPixelHorizontalRGB
SubPixelHorizontalBGR
SubPixelVerticalRGB
SubPixelVerticalBGR
SubPixelNone }
6. Extension Initialization
The name of this extension is "RANDR".
RRQueryVersion
client-major-version:
client-minor-version:
major-version:
minor-version:
CARD32
CARD32
CARD32
CARD32
7. Extension Requests
RRSelectInput
window: WINDOW
enable: SETofRRSELECTMASK
RRSetScreenConfig
window: WINDOW
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
size-id: SIZEID
rotation: ROTATION
rate: CARD16
status: RRCONFIGSTATUS
new-timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
root: WINDOW
subpixelOrder: SUBPIXELORDER
RRGetScreenInfo
window: WINDOW
rotations: SETofROTATION
root: WINDOW
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
size-id: SIZEID
rotation: ROTATION
rate: CARD16
sizes: LISTofSCREENSIZE
refresh: LISTofREFRESH
Errors: Window
RRGetScreenInfo returns information about the current and available
configurations for the screen associated with 'window'.
'rotations' contains the set of rotations and reflections supported
by the screen.
'root' is the root window of the screen.
'config-timestamp' indicates when the screen configuration
information last changed: requests to set the screen will fail
unless the timestamp indicates that the information the client
is using is up to date, to ensure clients can be well behaved
in the face of race conditions.
'timestamp' indicates when the configuration was last set.
'size-id' indicates which size is active.
'rate' is the current refresh rate. This is zero when the refresh
rate is unknown or on devices for which refresh is not relevant.
'sizes' is the list of possible frame buffer sizes (at the normal
orientation. Each size indicates both the linear physical size of
the screen and the pixel size.
'refresh' is the list of refresh rates for each size. Each element
of 'sizes' has a corresponding element in 'refresh'. An empty list
indicates no known rates, or a device for which refresh is not
relevant.
The default size of the screen (the size that would become the
current size when the server resets) is the first size in the
list.
7.1. Extension Requests added in version 1.2 of the extension
As introduced above, version 1.2 of the extension splits the screen size
from the crtc and output configuration, permitting the subset of the screen
presented by multiple outputs to be configured. As a separate notion, the
size of the screen itself may be arbitrarily configured within a defined
range. As crtcs and outputs are added and removed from the system, the set
returned by the extension will change so that applications can detect
dynamic changes in the display environment.
RRGetScreenSizeRange
window: WINDOW
Errors: Window
Returns the range of possible screen sizes. The screen may be set to
any size within this range.
RRSetScreenSize
window: WINDOW
width: CARD16
height: CARD16
width-in-millimeters: CARD32
height-in-millimeters: CARD32
RRGetScreenResources
window: WINDOW
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
crtcs: LISTofCRTC
outputs: LISTofOUTPUT
modes: LISTofMODEINFO
Errors: Window
RRGetScreenResources returns the list of outputs and crtcs connected
to the screen associated with 'window'.
'timestamp' indicates when the configuration was last set.
'config-timestamp' indicates when the configuration information last
changed. Requests to configure the output will fail unless the
timestamp indicates that the information the client is using is up
to date, to ensure clients can be well behaved in the face of race
conditions.
RRGetOutputInfo
output: OUTPUT
config-timestamp: TIMESTAMP
status: RRCONFIGSTATUS
timestamp: TIMESTAMP
crtc: CRTC
name: STRING
connection: CONNECTION
subpixel-order: SUBPIXELORDER
widthInMillimeters, heightInMillimeters: CARD32
crtcs: LISTofCRTC
clones: LISTofOUTPUT
modes: LISTofMODE
num-preferred: CARD16
Errors: Output
RRGetOutputInfo returns information about the current and available
configurations 'output'.
If 'config-timestamp' does not match the current configuration
timestamp (as returned by RRGetScreenResources), 'status' is set to
InvalidConfigTime and the remaining reply data is empty. Otherwise,
'status' is set to Success.
'timestamp' indicates when the configuration was last set.
'crtc' is the current source CRTC for video data, or Disabled if the
output is not connected to any CRTC.
'name' is a UTF-8 encoded string designed to be presented to the
user to indicate which output this is. E.g. "S-Video" or "DVI".
'connection' indicates whether the hardware was able to detect a
device connected to this output. If the hardware cannot determine
whether something is connected, it will set this to
UnknownConnection.
'subpixel-order' contains the resulting subpixel order of the
connected device to allow correct subpixel rendering.
'widthInMillimeters' and 'heightInMillimeters' report the physical
size of the displayed area. If unknown, or not really fixed (e.g.,
for a projector), these values are both zero.
'crtcs' is the list of CRTCs that this output may be connected to.
Attempting to connect this output to a different CRTC results in a
Match error.
'clones' is the list of outputs which may be simultaneously
connected to the same CRTC along with this output. Attempting to
connect this output with an output not in the 'clones' list
results in a Match error.
'modes' is the list of modes supported by this output. Attempting to
connect this output to a CRTC not using one of these modes results
in a Match error.
The first 'num-preferred' modes in 'modes' are preferred by the
monitor in some way; for fixed-pixel devices, this would generally
indicate which modes match the resolution of the output device.
RRListOutputProperties
output:OUTPUT
atoms: LISTofATOM
Errors: Output
This request returns the atoms of properties currently defined on
the output.
RRQueryOutputProperty
output: OUTPUT
property: ATOM
pending: BOOL
range: BOOL
immutable: BOOL
valid-values: LISTofINT32
RRConfigureOutputProperty
output: OUTPUT
property: ATOM
pending: BOOL
range: BOOL
valid-values: LISTofINT32
RRChangeOutputProperty
output: OUTPUT
property, type: ATOM
format: {8, 16, 32}
mode: { Replace, Prepend, Append }
data: LISTofINT8 or LISTofINT16 or LISTofINT32
is discarded.
format must
results). If
with the correct
RRDeleteOutputProperty
output: OUTPUT
property: ATOM
RRGetOutputProperty
output: OUTPUT
property: ATOM
type: ATOM or AnyPropertyType
long-offset, long-length: CARD32
delete: BOOL
pending: BOOL
RRCreateMode
window: WINDOW
modeinfo: MODEINFO
mode: MODE
Errors: Window, Name, Value
'modeinfo' provides a new mode for outputs on the screen
associated with 'window'. If the name of 'modeinfo' names an
existing mode, a Name error is returned. If some parameter of the
mode is not valid in some other way, a Value error is returned.
The returned 'mode' provides the id for the mode.
RRDestroyMode
mode: MODE
RRAddOutputMode
output: OUTPUT
mode: MODE
RRDeleteOutputMode
output: OUTPUT
mode: MODE
RRGetCrtcInfo
crtc: CRTC
config-timestamp: TIMESTAMP
status: RRCONFIGSTATUS
timestamp: TIMESTAMP
x, y: INT16
width, height: CARD16
mode: MODE
rotation: ROTATION
outputs: LISTofOUTPUT
rotations: SETofROTATION
possible-outputs: LISTofOUTPUT
Errors: Window
RRGetCrtcModes returns information about the current and available
configurations for the specified crtc connected to the screen
associated with 'window'.
If 'config-timestamp' does not match the current configuration
timestamp (as returned by RRGetScreenResources), 'status' is set to
InvalidConfigTime and the remaining reply data is empty. Otherwise,
'status' is set to Success.
'timestamp' indicates when the configuration was last set.
'x' and 'y' indicate the position of this CRTC within the screen
region. They will be set to 0 when the CRTC is disabled.
'width' and 'height' indicate the size of the area within the screen
presented by this CRTC. This may be different than the size of the
mode due to rotation, the projective transform, and the Border property
described below. They will be set to 0 when the CRTC is disabled.
'mode' indicates which mode is active, or None indicating that the
CRTC has been disabled and is not displaying the screen contents.
'rotation' indicates the active rotation. It is set to Rotate_0
when the CRTC is disabled.
'outputs' is the list of outputs currently connected to this CRTC
and is empty when the CRTC is disabled.
'rotations' contains the set of rotations and reflections supported
by the CRTC.
'possible-outputs' lists all of the outputs which may be connected
to this CRTC.
RRSetCrtcConfig
crtc: CRTC
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
x, y: INT16
mode: MODE
rotation: ROTATION
outputs: LISTofOUTPUT
status: RRCONFIGSTATUS
new-timestamp: TIMESTAMP
If 'timestamp' is less than the time when the configuration was last
successfully set, the request is ignored and InvalidTime returned in
status.
If 'config-timestamp' is not equal to when the monitor's
configuration last changed, the request is ignored and
InvalidConfigTime returned in status. This could occur if the
monitor changed since you last made a RRGetScreenInfo request,
perhaps by a different monitor being connected to the machine.
Rather than allowing an incorrect call to be executed based on stale
data, the server will ignore the request.
'x' and 'y' contain the desired location within the screen for this
monitor's content. 'x' and 'y' must be within the screen size, else
a Value error results.
'mode' is either the desired mode or None indicating the CRTC should
be disabled. If 'mode' is not one of these values, a Value
error results. 'mode' must be valid for all of the configured outputs,
else a Match error.
'rotation' contains the desired rotation along with which
reflections should be enabled. The rotation and reflection values
must be among those allowed for this monitor, else a Value error
results.
'outputs' contains the set of outputs that this CRTC should be
connected to. The set must be among the list of acceptable output
sets for this CRTC or a Match error results.
If 'mode' is None, then 'outputs' must be empty, else a Match error
results. Conversely, if 'mode' is not None, then 'outputs' must not be
empty, else a Match error results.
This request may fail for other indeterminate reasons, in which case
'status' will be set to Failed and no configuration change will be
made.
This request sets the CRTC to the specified position, mode, rotation
and reflection. The entire area of the CRTC must fit within the
screen size, else a Match error results. As an example, rotating the
screen so that a single CRTC fills the entire screen before and
after may necessitate disabling the CRTC, resizing the screen,
then re-enabling the CRTC at the new configuration to avoid an
invalid intermediate configuration.
If panning is enabled, the width and height of the panning and the
tracking areas are clamped to the new mode size.
Disabled panning axes remain disabled.
Panning borders are disabled if their requirements are no longer met
(see RRSetPanning).
When this request succeeds, 'status' contains Success and the
requested changes to configuration will have been made.
'new-time-stamp' contains the time at which this request was
executed.
RRGetCrtcGammaSize
crtc: CRTC
size: CARD16
Errors: Crtc
This request returns the size of the gamma ramps used by 'crtc'.
RRGetCrtcGamma
crtc: CRTC
red: LISTofCARD16
green: LISTofCARD16
blue: LISTofCARD16
Errors: Crtc
This request returns the currently set gamma ramps for 'crtc'. All
three lists will be the size returned by the RRGetCrtcGammaSize
request.
RRSetCrtcGamma
crtc: CRTC
red: LISTofCARD16
green: LISTofCARD16
blue: LISTofCARD16
RRGetScreenResourcesCurrent
window: WINDOW
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
crtcs: LISTofCRTC
outputs: LISTofOUTPUT
modes: LISTofMODEINFO
Errors: Window
RRGetScreenResourcesCurrent returns the list of outputs and crtcs
connected to the screen associated with 'window'.
'timestamp' indicates when the configuration was last set.
'config-timestamp' indicates when the configuration information last
changed. Requests to configure the output will fail unless the
timestamp indicates that the information the client is using is up
to date, to ensure clients can be well behaved in the face of race
conditions.
RRSetCrtcTransform
crtc: CRTC
transform: TRANSFORM
filter: STRING8
values: LISTofFIXED
RRGetCrtcTransform
crtc: CRTC
pending-transform: TRANSFORM
pending-filter: STRING8
pending-values: LISTofFIXED
current-transform: TRANSFORM
current-filter: STRING8
current-values: LISTofFIXED
This request returns the pending and current transforms for the
specified CRTC. The pending transform will be the same as the current
transform if no new pending transform has been set since the last call
to RRSetCrtcConfig.
RRGetPanning
crtc: CRTC
status: RRCONFIGSTATUS
timestamp: TIMESTAMP
left, top, width, height: CARD16
track_left, track_top, track_width, track_height: CARD16
border_left, border_top, border_right, border_bottom: INT16
Errors: Crtc
Version 1.3 adds panning support again. If multiple crtcs are active
the panning behavior can be defined per crtc individually.
RRGetPanning returns information about the currently set panning
configuration for the specified crtc. If the CRTC does not support
panning, all fields (except timestamp) will be 0.
'timestamp' indicates when the configuration was last set.
All other entries are explained for RRSetPanning.
RRSetPanning
crtc: CRTC
timestamp: TIMESTAMP
left, top, width, height: CARD16
track_left, track_top, track_width, track_height: CARD16
border_left, border_top, border_right, border_bottom: INT16
status: RRCONFIGSTATUS
new-timestamp: TIMESTAMP
framebuffer
panning area
'left', 'top', 'width', and 'height' contain the total panning area
for this CRTC. 'width' has to be larger than or equal to the CRTC's
width or 0, and 'left'+'width' must be within the screen size, else a
Match error results. Equivalent restrictions for the height exist.
'width' or 'height' set to 0 indicate that panning should be disabled
on the according axis. Setting 'width'/'height' to the CRTC's
width/height will disable panning on the X/Y axis as well, but
RRSetScreenSize will silently enable panning if the screen size is
increased. This does not happen if set to 0.
CRTC
panning area
tracking area
CRTC
border_right
panning area
RRSetOutputPrimary
window: WINDOW
output: OUTPUT
ConfigureNotify
appropriate root
call. This request
outputs that gained
RRGetOutputPrimary
window: WINDOW
output: OUTPUT
Errors: Window
RRGetOutputPrimary returns the primary output for the screen.
RRGetProviders
window : WINDOW
timestamp: TIMESTAMP
providers: LISTofPROVIDER
Errors: Window
RRGetPRoviders returns the list of providers connected to the screen
associated with 'window'.
'timestamp' indicates when the configuration was last set.
'providers' contains the list of PROVIDERs associated with the
screen.
RRGetProviderInfo
provider: PROVIDER
capabilities: PROVIDER_CAPS
name: STRING
crtcs: LISTofCRTC
outputs: LISTofOUTPUT
associated_providers: LISTofPROVIDERS
associated_provider_capability: LISTofPROVIDER_CAPS
Errors: Provider
RRGetProviderInfo return information about the specified provider.
The capabilites of the current provider are returned, along with
the list of providers currently associated with this provider and
the capability they are associated with. It also provides the list
of crtcs and outputs that this provider is responsible for.
'name' is a UTF-8 encoded string to be presented to the user to
indicate the device or driver supplied name.
RRSetProviderOffloadSink
provider: PROVIDER
sink_provider: PROVIDER
Errors: Provider
RRSetOffloadSink sets the offload sink for this provider to the
specified provider.
RRSetProviderOutputSource
provider: PROVIDER
source_provider: PROVIDER
Errors: Provider
RRSetOutputSource sets the output source for this provider to the
specified provider.
RRListProviderProperties
provider:PROVIDERS
atoms: LISTofATOM
Errors: Provider
This request returns the atoms of properties currently defined on
the provider.
RRQueryProviderProperty
provider: PROVIDER
property: ATOM
pending: BOOL
range: BOOL
immutable: BOOL
valid-values: LISTofINT32
RRConfigureProviderProperty
provider: PROVIDER
property: ATOM
pending: BOOL
range: BOOL
valid-values: LISTofINT32
RRChangeProviderProperty
provider: PROVIDER
property, type: ATOM
format: {8, 16, 32}
mode: { Replace, Prepend, Append }
data: LISTofINT8 or LISTofINT16 or LISTofINT32
is discarded.
format must
results). If
with the correct
RRGetProviderProperty
provider: PROVIDER
property: ATOM
type: ATOM or AnyPropertyType
long-offset, long-length: CARD32
delete: BOOL
pending: BOOL
the format is the actual format of the property (never zero), and
the bytes-after and value are as follows, given:
N = actual length of the stored property in bytes
(even if the format is 16 or 32)
I = 4 offset
T = N - I
L = MINIMUM(T, 4 long-length)
A = N - (I + L)
If 'pending' is true, and if the property holds a pending value,
then the value returned will be the pending value of the property
rather than the current value. The returned value starts at byte
index I in the property (indexing from 0), and its length in bytes
is L. However, it is a Value error if long-offset is given such
that L is negative. The value of bytes-after is A, giving the
number of trailing unread bytes in the stored property. If delete
is True and the bytes-after is zero, the property is also deleted
from the provider, and a RRProviderPropertyNotify event is generated.
8. Extension Events
Clients MAY select for ConfigureNotify on the root window to be
informed of screen changes. This may be advantageous if all your
client needs to know is the size of the root window, as it avoids
round trips to set up the extension.
RRScreenChangeNotify is sent if RRSelectInput has requested it
whenever properties of the screen change, which may be due to external
factors, such as re-cabling a monitor, etc.
RRScreenChangeNotify
rotation: ROTATION;
sequenceNumber: CARD16
timestamp: TIMESTAMP
configTimestamp: TIMESTAMP
root: WINDOW
window: WINDOW
size-id: SIZEID
subpixelOrder: SUBPIXELORDER
widthInPixels: CARD16
heightInPixels: CARD16
widthInMillimeters: CARD16
heightInMillimeters: CARD16
new rotation
low 16 bits of request seq. number
time screen was changed
time config data was changed
root window of screen
window requesting notification
index of new SCREENSIZE
order of subpixels
width in pixels of the new SCREENSIZE
height in pixels of the new SCREENSIZE
width in mm of the new SCREENSIZE
height in mm of the new SCREENSIZE
RROutputChangeNotify:
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
window: WINDOW
output: OUTPUT
crtc: CRTC
mode: MODE
connection: CONNECTION
RROutputPropertyNotify:
window: WINDOW
output: OUTPUT
atom: ATOM
time: TIMESTAMP
subpixel-order: SUBPIXELORDER
state: { NewValue, Deleted }
RRCrtcChangeNotify
timestamp: TIMESTAMP
window: WINDOW
crtc: CRTC
mode: MODE
rotation: ROTATION;
x: INT16
y: INT16
width: CARD16
height: CARD16
RRProviderChangeNotify:
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
window: WINDOW
provider: PROVIDER
role: CRTC
This event is generated whenever the role for a provider has changed
and is sent to requesting clients. 'timestamp' indicates when the
provider configuration was changed by a client.
'config-timestamp' says when the last time the available
configurations changed. 'root' is the root of the screen the change
occurred on, 'window' is window selecting for this event. The
precise change can be detected by examining the new state of the
system.
RRProviderPropertyNotify:
window: WINDOW
provider: PROVIDER
atom: ATOM
time: TIMESTAMP
state: { NewValue, Deleted }
RRResourceChangeNotify:
window: WINDOW
time: TIMESTAMP
9. Properties
Properties are used for output specific parameters, and for announcing
static or rarely changing data. Announced data is typically
immutable. Properties are also used for evaluating new parameters
before adding them to the RandR protocol.
The following properties are hereby declared official, and drivers SHOULD
prefix driver specific properties with '_', unless they are planned to be
added to this specification. List values, that are not declared by the table
below, and will remain driver specific or are not planned to be added to this
specification, SHOULD be prefixed with "_" as well in order to avoid name
space or semantics clashes with future extensions of these values.
Beginning with version 1.3 of the RandR extension, certain properties
are mandatory and MUST be provided by implementations. Earlier
versions of the RandR extension MAY provide these properties as well,
as long as the semantics are not altered. Clients SHOULD fall back
gracefully to lower version functionality, though, if the driver
doesn't handle a mandatory property correctly.
9.1 Known properties
"Backlight"
Type:
Format:
Num. items:
Flags:
Range/List:
aka RR_PROPERTY_BACKLIGHT
INTEGER
32
1
0-x (driver specific)
aka RR_PROPERTY_CLONE_LIST
ATOM
32
2*n
Immutable
0-
aka RR_PROPERTY_COMPATIBILITY_LIST
ATOM
32
2*n
Immutable
0-
aka RR_PROPERTY_CONNECTOR_NUMBER
INTEGER
32
1
Immutable, Static
0-
aka RR_PROPERTY_CONNECTOR_TYPE
Type:
Format:
Num items:
Flags:
Range/List:
ATOM
32
1
Immutable, Static
unknown VGA DVI DVII DVIA DVID HDMI Panel
TV TV-Composite TV-SVideo TV-Component
TV-SCART TV-C4 DisplayPort
aka RR_PROPERTY_RANDR_EDID
INTEGER
8
n
Immutable
-
aka RR_PROPERTY_SIGNAL_FORMAT
ATOM
32
1
unknown VGA TMDS LVDS Composite Composite-PAL
Composite-NTSC Composite-SECAM SVideo
Component DisplayPort
aka RR_PROPERTY_SIGNAL_FORMAT
ATOM
32
n
For Composite signals:
NTSC NTSC-M NTSC-J NTSC-N NTSC-4.43 NTSC-film
aka RR_PROPERTY_BORDER
CARDINAL
16
0, 1, 2, or 4
Immutable
0-
If the length of the property is less than four when the CRTC is
configured, the missing values are assumed to be zero. If the length is
greater than four, the extra values are ignored.
If the width of the mode is less than or equal to the sum of the left
and right borders, then the left and right border settings are ignored.
Likewise, if the height of the mode is less than or equal to the sum of
the top and bottom borders, the top and bottom borders are ignored.
"BorderDimensions"
Type:
Format:
Num items:
Flags:
Range/List:
aka RR_PROPERTY_BORDER_DIMENSIONS
CARDINAL
8
1
Immutable, Static
0, 1, 2, or 4
This property lists how many border adjustment parameters can actually
be used:
0
1
2
4
=
=
=
=
EDID
Immutable
yes
Mandatory since
n/a
CloneList
CompatibilityList
ConnectorNumber
ConnectorType
SignalFormat
SignalProperties
Immutable
yes
yes
yes: static
yes: static
no
no
Mandatory since
not mandatory
not mandatory
not mandatory
RandR 1.3
RandR 1.3
not mandatory
Backlight
Immutable
no
Mandatory since
not mandatory
Border
BorderDimensions
Immutable
yes
yes: static
Mandatory since
not mandatory
not mandatory
ROTATION
0x0001
0x0002
0x0004
0x0008
0x0010
0x0020
Rotate_0
Rotate_90
Rotate_180
Rotate_270
Reflect_X
Reflect_Y
RRSELECTMASK
0x0001 ScreenChangeNotifyMask
0x0002 CrtcChangeNotifyMask
0x0004 OutputChangeNotifyMask
0x0008 OutputPropertyNotifyMask
0x0010 ProviderChangeNotifyMask
0x0020 ProviderPropertyNotifyMask
0x0040 ResourceChangeNotifyMask
Added
Added
Added
Added
Added
Added
in
in
in
in
in
in
version
version
version
version
version
version
1.2
1.2
1.2
1.4
1.4
1.4
RRCONFIGSTATUS
0x0 Success
0x1 InvalidConfigTime
0x2 InvalidTime
0x3 Failed
MODEINFO (32)
4
CARD32
2
CARD16
2
CARD16
4
CARD32
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
4
SETofMODEFLAG
id
width in pixels
height in pixels
dot clock
h sync start
h sync end
h total
h skew
v sync start
v sync end
v total
name length
mode flags
MODEFLAG
0x00000001
0x00000002
0x00000004
0x00000008
0x00000010
0x00000020
0x00000040
0x00000080
0x00000100
0x00000200
0x00000400
0x00000800
0x00001000
0x00002000
HSyncPositive
HSyncNegative
VSyncPositive
VSyncNegative
Interlace
DoubleScan
CSync
CSyncPositive
CSyncNegative
HSkewPresent
BCast
PixelMultiplex
DoubleClock
ClockDivideBy2
CONNECTION
0
1
2
Connected
Disconnected
UnknownConnection
Opcodes 1 and 3 were used in the 0.0 protocols, and will return
errors if used in version 1.0.
RRQueryVersion
1
1
2
4
4
CARD8
0
3
CARD32
CARD32
major opcode
RandR opcode
length
major version
minor version
1
1
2
4
1
1
Reply
unused
sequence number
reply length
major version
minor version
CARD16
0
CARD32
CARD32
RRSetScreenConfig
1
1
2
4
4
4
2
2
2
2
CARD8
2
6
WINDOW
TIMESTAMP
TIMESTAMP
SIZEID
ROTATION
CARD16
CARD16
major opcode
RandR opcode
length
window on screen to be configured
timestamp
config timestamp
size index
rotation/reflection
refresh rate (1.1 only)
pad
1
1
2
4
4
4
4
2
2
4
4
1
RRCONFIGSTATUS
CARD16
0
TIMESTAMP
TIMESTAMP
WINDOW
SUBPIXELORDER
CARD16
CARD32
CARD32
Reply
status
sequence number
reply length
new timestamp
new configuration timestamp
root
subpixel order defined in Render
pad4
pad5
pad6
RRSelectInput
1
1
2
4
2
2
CARD8
4
3
WINDOW
SETofRRSELECTMASK
CARD16
major opcode
RandR opcode
length
window
enable
pad
RRGetScreenInfo
1
1
CARD8
5
major opcode
RandR opcode
2
4
2
WINDOW
length
window
1
1
2
4
4
4
4
2
2
2
2
2
2
1
CARD8
CARD16
0
WINDOW
TIMESTAMP
TIMESTAMP
CARD16
SIZEID
ROTATION
CARD16
CARD16
CARD16
Reply
set of Rotations
sequence number
reply length
root window
timestamp
config timestamp
number of SCREENSIZE following
current size index
current rotation and reflection
current rate (added in version 1.1)
length of rate info (number of CARD16s)
pad
SCREENSIZE
2
CARD16
2
CARD16
2
CARD16
2
CARD16
width in pixels
height in pixels
width in millimeters
height in millimeters
REFRESH
2
CARD16
2n
CARD16
RRGetScreenSizeRange
1
CARD8
1
6
2
2
4
WINDOW
1
1
1
2
CARD16
4
0
2
CARD16
2
CARD16
2
CARD16
2
CARD16
16
RRSetScreenSize
1
CARD8
1
7
2
5
4
WINDOW
2
CARD16
2
CARD16
4
CARD32
4
CARD32
RRGetScreenResources
major opcode
RandR opcode
length
window
Reply
unused
sequence number
reply length
minWidth
minHeight
maxWidth
maxHeight
unused
major opcode
RandR opcode
length
window
width
height
width in millimeters
height in millimeters
1
1
2
4
CARD8
8
2
WINDOW
major opcode
RandR opcode
length
window
1
1
2
4
4
4
2
2
2
2
8
4c
4o
32m
b
p
Reply
unused
sequence number
reply length
timestamp
config-timestamp
number of CRTCs
number of outputs
number of modeinfos
total bytes in mode names
unused
crtcs
outputs
modeinfos
mode names
unused, p=pad(b)
CARD16
c+o+8m+(b+p)/4
TIMESTAMP
TIMESTAMP
c
o
m
b
LISTofCRTC
LISTofOUTPUT
LISTofMODEINFO
STRING8
RRGetOutputInfo
1
CARD8
1
9
2
3
4
OUTPUT
4
TIMESTAMP
1
1
1
RRCONFIGSTATUS
2
CARD16
4
1+c+m+(n+p)/4
4
TIMESTAMP
4
CRTC
4
CARD32
4
CARD32
1
CONNECTION
1
SUBPIXELORDER
2
c
2
m
2
p
2
o
2
n
4c
LISTofCRTC
4m
LISTofMODE
4o
LISTofOUTPUT
n
STRING8
p
RRListOutputProperties
1
CARD8
1
10
2
2
4
OUTPUT
1
1
1
major opcode
RandR opcode
length
output
config-timestamp
Reply
status
sequence number
reply length
timestamp
current connected crtc
width in millimeters
height in millimeters
connection
subpixel-order
number of CRTCs
number of modes
number of preferred modes
number of clones
length of name
crtcs
modes
clones
name
unused, p=pad(n)
major opcode
RandR opcode
length
output
Reply
unused
2
4
2
22
4n
CARD16
n
n
LISTofATOM
RRQueryOutputProperty
1
CARD8
1
11
2
3
4
OUTPUT
4
ATOM
1
1
1
2
CARD16
4
n
1
BOOL
1
BOOL
1
BOOL
21
4n
LISTofINT32
RRConfigureOutputProperty
1
CARD8
1
12
2
4+n
4
OUTPUT
4
ATOM
1
BOOL
1
BOOL
2
4n
LISTofINT32
RRChangeOutputProperty
1
CARD8
1
13
2
6+(n+p)/4
4
OUTPUT
4
ATOM
4
ATOM
1
CARD8
1
0
Replace
1
Prepend
2
Append
2
4
CARD32
LISTofBYTE
sequence number
reply length
number of ATOMs in atoms
unused
atoms
major opcode
RandR opcode
request length
output
property
Reply
unused
sequence number
reply length
pending
range
immutable
unused
valid values
major opcode
RandR opcode
request length
output
property
pending
range
unused
valid values
major opcode
RandR opcode
request length
output
property
type
format
mode
unused
length of data in format units
(= n for format = 8)
(= n/2 for format = 16)
(= n/4 for format = 32)
data
(n is a multiple of 2 for format = 16)
(n is a multiple of 4 for format = 32)
unused, p=pad(n)
RRDeleteOutputProperty
1
CARD8
1
14
2
3
4
OUTPUT
4
ATOM
major opcode
RandR opcode
request length
output
property
RRGetOutputProperty
1
CARD8
major opcode
1
15
RandR opcode
2
7
request length
4
OUTPUT
output
4
ATOM
property
4
ATOM
type
0
AnyPropertyType
4
CARD32
long-offset
4
CARD32
long-length
1
BOOL
delete
1
BOOL
pending
2
unused
1
1
Reply
1
CARD8
format
2
CARD16
sequence number
4
(n+p)/4
reply length
4
ATOM
type
0
None
4
CARD32
bytes-after
4
CARD32
length of value in format units
(= 0 for format = 0)
(= n for format = 8)
(= n/2 for format = 16)
(= n/4 for format = 32)
12
unused
n
LISTofBYTE
value
(n is zero for format = 0)
(n is a multiple of 2 for format = 16)
(n is a multiple of 4 for format = 32)
p
unused, p=pad(n)
RRCreateMode
1
CARD8
1
16
2
12+(n+p)/4
4
WINDOW
32
MODEINFO
n
STRING8
p
1
1
1
2
CARD16
4
0
4
MODE
20
RRDestroyMode
major opcode
RandR opcode
length
window
mode
mode name
unused, p=pad(n)
Reply
unused
sequence number
reply length
mode
unused
1
1
2
4
CARD8
17
2
MODE
major opcode
RandR opcode
length
mode
RRAddOutputMode
1
CARD8
1
18
2
3
4
OUTPUT
4
MODE
major opcode
RandR opcode
length
output
mode
RRDeleteOutputMode
1
CARD8
1
19
2
3
4
OUTPUT
4
MODE
major opcode
RandR opcode
length
output
mode
RRGetCrtcInfo
1
CARD8
1
20
2
3
4
CRTC
4
TIMESTAMP
1
1
1
RRCONFIGSTATUS
2
CARD16
4
o+p
4
TIMESTATMP
2
INT16
2
INT16
2
CARD16
2
CARD16
4
MODE
2
ROTATION
2
ROTATION
2
o
2
p
4o
LISTofOUTPUT
4p
LISTofOUTPUT
Reply
status
sequence number
reply length
timestamp
x
y
width
height
mode
current rotation and reflection
set of possible rotations
number of outputs
number of possible outputs
outputs
possible outputs
RRSetCrtcConfig
1
CARD8
1
21
2
7+2n
4
CRTC
4
TIMESTAMP
4
TIMESTAMP
2
INT16
2
INT16
4
MODE
2
ROTATION
2
8n
LISTofOUTPUT
major opcode
RandR opcode
length
crtc
timestamp
config timestamp
x
y
mode
rotation/reflection
unused
outputs
major opcode
RandR opcode
length
crtc
config-timestamp
1
1
2
4
4
20
1
RRCONFIGSTATUS
CARD16
0
TIMESTAMP
RRGetCrtcGammaSize
1
CARD8
1
22
2
2
4
CRTC
1
1
1
2
CARD16
4
0
2
CARD16
22
Reply
status
sequence number
reply length
new timestamp
unused
major opcode
RandR opcode
length
crtc
Reply
unused
sequence number
reply length
size
unused
RRGetCrtcGamma
1
CARD8
1
23
2
2
4
CRTC
1
1
1
2
CARD16
4
(6n+2)/4
2
n
20
2n
LISTofCARD16
2n
LISTofCARD16
2n
LISTofCARD16
p
Reply
unused
sequence number
reply length
size
unused
red
green
blue
unused, p=pad(6n)
RRSetCrtcGamma
1
CARD8
1
24
2
3+(6n+2)/4
4
CRTC
2
n
2
2n
LISTofCARD16
2n
LISTofCARD16
2n
LISTofCARD16
p
major opcode
RandR opcode
length
crtc
size
unused
red
green
blue
unused, p=pad(6n)
major opcode
RandR opcode
length
crtc
RRGetScreenResourcesCurrent
1
CARD8
1
25
major opcode
RandR opcode
2
4
2
WINDOW
length
window
1
1
2
4
4
4
2
2
2
2
8
4c
4o
32m
b
p
Reply
unused
sequence number
reply length
timestamp
config-timestamp
number of CRTCs
number of outputs
number of modeinfos
total bytes in mode names
unused
crtcs
outputs
modeinfos
mode names
unused, p=pad(b)
CARD16
c+o+8m+(b+p)/4
TIMESTAMP
TIMESTAMP
c
o
m
b
LISTofCRTC
LISTofOUTPUT
LISTofMODEINFO
STRING8
RRSetCrtcTransform
1
CARD8
1
26
2
12+(n+p)/4+v
4
CRTC
36
TRANSFORM
2
CARD16
2
n
STRING8
p
4v
FIXED
major opcode
RandR opcode
length
crtc
transform
filter length
unused
filter name
unused, p=pad(n)
filter params
RRGetCrtcTransform
1
CARD8
major opcode
1
27
RandR opcode
2
2
length
4
CRTC
crtc
1
1
Reply
1
unused
2
CARD16
sequence number
4
16+(pn+pnp)/4+(cn+cnp)/4+pf+cf reply length
36
TRANSFORM
pending transform
1
BOOL
has transforms
3
unused
36
TRANSFORM
current transform
4
unused
2
pn
pending filter name length
2
pf
pending filter num params
2
cn
current filter name length
2
cf
current filter num params
pn
STRING8
pending filter name
pnp
unused, pnp=pad(pn)
4*pf
FIXED
pending filter params
cn
STRING8
current filter name
cnp
unused, cnp=pad(cn)
4*cf
FIXED
RRGetPanning
1
CARD8
1
28
2
2
4
CRTC
1
1
1
RRCONFIGSTATUS
2
CARD16
4
1
4
TIMESTAMP
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
INT16
2
INT16
2
INT16
2
INT16
RRSetPanning
1
CARD8
1
29
2
9
4
CRTC
4
TIMESTAMP
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
CARD16
2
INT16
2
INT16
2
INT16
2
INT16
1
1
1
RRCONFIGSTATUS
2
CARD16
4
0
4
TIMESTAMP
20
major opcode
RandR opcode
length
crtc
Reply
status
sequence number
reply length
timestamp
left
top
width
height
track_left
track_top
track_width
track_height
border_left
border_top
border_right
border_bottom
major opcode
RandR opcode
length
crtc
timestamp
left
top
width
height
track_left
track_top
track_width
track_height
border_left
border_top
border_right
border_bottom
Reply
status
sequence number
reply length
new timestamp
unused
RRSetOutputPrimary
1
CARD8
1
30
major opcode
RandR opcode
2
4
4
3
WINDOW
OUTPUT
length
window
output
RRGetOutputPrimary
1
CARD8
1
31
2
2
4
WINDOW
1
1
1
2
CARD16
4
CARD32
4
OUTPUT
4
CARD32
4
CARD32
4
CARD32
4
CARD32
major opcode
RandR opcode
length
window
Reply
unused
sequence number
length
output
pad1
pad2
pad3
pad4
RRGetProviders
1
CARD8
1
32
2
2
4
WINDOW
1
1
1
2
CARD16
4
CARD32
4
TIMESTAMP
2
p
2
CARD16
4
CARD32
4p
LISTofPROVIDERS
major opcode
RandR opcode
length
window
Reply
unused
sequence number
length
timestamp
number of Providers
maximum masters
flags
providers
RRGetProviderInfo
1
CARD8
1
33
2
3
4
PROVIDER
4
TIMESTAMP
1
1
1
RRCONFIGSTATUS
2
CARD16
4
1+c+o+(a*2)+(n+p)/4
4
TIMESTATMP
4
CARD32
2
c
2
o
2
a
2
n
major opcode
RandR opcode
length
provider
config-timestamp
Reply
status
sequence number
reply length
timestamp
capabilites
number of crtcs
number of outputs
number of associated providers
length of name
4c
4o
4a
4a
n
p
LISTofCRTC
LISTofOUTPUT
LISTofPROVIDER
CARD32
STRING8
crtcs
outputs
associated providers
associated provider capability
name
unused, p=pad(n)
RRSetProviderOffloadSink
1
CARD8
1
34
2
2
4
PROVIDER
4
PROVIDER
4
TIMESTAMP
major opcode
RandR opcode
length
provider
offload sink provider
timestamp
RRSetProviderOutputSource
1
CARD8
1
35
2
2
4
PROVIDER
4
PROVIDER
4
TIMESTAMP
major opcode
RandR opcode
length
provider
output source provider
timestamp
RRListProviderProperties
1
CARD8
1
36
2
2
4
PROVIDER
1
1
1
2
CARD16
4
n
2
n
22
4n
LISTofATOM
RRQueryProviderProperty
1
CARD8
1
37
2
3
4
PROVIDER
4
ATOM
1
1
1
2
CARD16
4
n
1
BOOL
1
BOOL
1
BOOL
21
4n
LISTofINT32
RRConfigureProviderProperty
1
CARD8
major opcode
RandR opcode
length
provider
Reply
unused
sequence number
reply length
number of ATOMs in atoms
unused
atoms
major opcode
RandR opcode
request length
provider
property
Reply
unused
sequence number
reply length
pending
range
immutable
unused
valid values
major opcode
1
2
4
4
1
1
2
4n
38
4+n
PROVIDER
ATOM
BOOL
BOOL
LISTofINT32
RRChangeProviderProperty
1
CARD8
1
39
2
6+(n+p)/4
4
PROVIDER
4
ATOM
4
ATOM
1
CARD8
1
0
Replace
1
Prepend
2
Append
2
4
CARD32
LISTofBYTE
RRDeleteProviderProperty
1
CARD8
1
40
2
3
4
PROVIDER
4
ATOM
RRGetProviderProperty
1
CARD8
1
41
2
7
4
PROVIDER
4
ATOM
4
ATOM
0
AnyPropertyType
4
CARD32
4
CARD32
1
BOOL
1
BOOL
2
1
1
1
CARD8
2
CARD16
4
(n+p)/4
4
ATOM
RandR opcode
request length
provider
property
pending
range
unused
valid values
major opcode
RandR opcode
request length
provider
property
type
format
mode
unused
length of data in format units
(= n for format = 8)
(= n/2 for format = 16)
(= n/4 for format = 32)
data
(n is a multiple of 2 for format = 16)
(n is a multiple of 4 for format = 32)
unused, p=pad(n)
major opcode
RandR opcode
request length
provider
property
major opcode
RandR opcode
request length
provider
property
type
long-offset
long-length
delete
pending
unused
Reply
format
sequence number
reply length
type
4
4
0
None
CARD32
CARD32
12
n
LISTofBYTE
bytes-after
length of value in format units
(= 0 for format = 0)
(= n for format = 8)
(= n/2 for format = 16)
(= n/4 for format = 32)
unused
value
(n is zero for format = 0)
(n is a multiple of 2 for format = 16)
(n is a multiple of 4 for format = 32)
unused, p=pad(n)
RRScreenChangeNotify
1
Base + 0
1
ROTATION
2
CARD16
4
TIMESTAMP
4
TIMESTAMP
4
WINDOW
4
WINDOW
2
SIZEID
2
SUBPIXELORDER
2
CARD16
2
CARD16
2
CARD16
2
CARD16
code
new rotation and reflection
sequence number
timestamp
configuration timestamp
root window
request window
size ID
subpixel order defined in Render
width in pixels
height in pixels
width in millimeters
height in millimeters
RRCrtcChangeNotify
1
Base + 1
1
0
2
CARD16
4
TIMESTAMP
4
WINDOW
4
CRTC
4
MODE
2
ROTATION
2
2
INT16
2
INT16
2
CARD16
2
CARD16
code
sub-code
sequence number
timestamp
request window
crtc affected
mode in use
new rotation and reflection
unused
x
y
width
height
RROutputChangeNotify
1
Base + 1
1
1
2
CARD16
4
TIMESTAMP
4
TIMESTAMP
4
WINDOW
code
sub-code
sequence number
timestamp
configuration timestamp
request window
4
4
4
2
1
1
OUTPUT
CRTC
MODE
ROTATION
CONNECTION
SUBPIXELORDER
RROutputPropertyNotify
1
Base + 1
1
2
2
CARD16
4
WINDOW
4
OUTPUT
4
ATOM
4
TIMESTAMP
1
0
NewValue
1
Deleted
11
output affected
crtc in use
mode in use
rotation in use
connection status
subpixel order
code
sub-code
sequence number
window
output
atom
time
state
unused
RRProviderChangeNotify
1
Base + 1
code
1
1
sub-code
2
CARD16
sequence number
4
TIMESTAMP
timestamp
4
WINDOW
request window
4
PROVIDER
provider affected
16
unused
RRProviderPropertyNotify
1
Base + 1
code
1
2
sub-code
2
CARD16
sequence number
4
WINDOW
window
4
PROVIDER
provider
4
ATOM
atom
4
TIMESTAMP
time
1
state
0
NewValue
1
Deleted
11
unused
RRResourceChangeNotify
1
Base + 1
code
1
2
sub-code
2
CARD16
sequence number
4
TIMESTAMP
time
4
WINDOW
window
20
unused
ERRORS
Base
Base
Base
Base
+
+
+
+
0
1
2
3
Output
Crtc
Mode
Provider
Bibliography
[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate
Extension - RandR", Proceedings of the 2001 USENIX Annual
Technical Conference, Boston, MA
[RENDER]
Packard, Keith, "The X Rendering Extension", work in progress,
http://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt