222 lines
7.3 KiB
Plaintext
222 lines
7.3 KiB
Plaintext
The DAMAGE Extension
|
|
Protocol Version 1.1
|
|
Document Revision 1
|
|
2007-01-08
|
|
|
|
Keith Packard
|
|
keithp@keithp.com
|
|
|
|
Eric Anholt
|
|
eric@anholt.net
|
|
Open Source Technology Center
|
|
Intel Corporation
|
|
1. Introduction
|
|
|
|
Monitoring the regions affected by rendering has wide-spread use, from
|
|
VNC-like systems scraping the screen to screen magnifying applications
|
|
designed to aid users with limited visual acuity. The DAMAGE extension is
|
|
designed to make such applications reasonably efficient in the face of
|
|
server-client latency.
|
|
|
|
2. Acknolwedgements
|
|
|
|
As usual, the author had significant input from many people, in particular:
|
|
|
|
+ Havoc Pennington who designed and implemented a Damage extension
|
|
last year which was then lost to the mists of time.
|
|
|
|
+ Bill Haneman whose work on accessibility in the Gnome environment
|
|
is legendary.
|
|
|
|
+ Jim Gettys who found a way to avoid streaming damage rectangles
|
|
to the client in many cases.
|
|
|
|
+ Owen Taylor who suggested that streaming damage rectangles may
|
|
be warranted in some cases after all.
|
|
|
|
3. Damage Model
|
|
|
|
We call changes made to pixel contents of windows and pixmaps 'damage'
|
|
throughout this extension. Another notion of 'damage' are drawable regions
|
|
which are in need of redisplay to repair the effects of window manipulation
|
|
or other data loss. This extension doesn't deal with this second notion at
|
|
all; suggestions on a better term which isn't easily conflated with existing
|
|
notions are eagerly solicited.
|
|
|
|
Damage accumulates as drawing occurs in the drawable. Each drawing operation
|
|
'damages' one or more rectangular areas within the drawable. The rectangles
|
|
are guaranteed to include the set of pixels modified by each operation, but
|
|
may include significantly more than just those pixels. The desire is for
|
|
the damage to strike a balance between the number of rectangles reported and
|
|
the extraneous area included. A reasonable goal is for each primitive
|
|
object drawn (line, string, rectangle) to be represented as a single
|
|
rectangle and for the damage area of the operation to be the union of these
|
|
rectangles.
|
|
|
|
The DAMAGE extension allows applications to either receive the raw
|
|
rectangles as a stream of events, or to have them partially processed within
|
|
the X server to reduce the amount of data transmitted as well as reduce the
|
|
processing latency once the repaint operation has started.
|
|
|
|
Damage to a window reflects both drawing within the window itself as well as
|
|
drawing within any inferior window that affects pixels seen by
|
|
IncludeInferiors rendering operations. To reduce the computational
|
|
complexity of this, the DAMAGE extension allows the server to monitor all
|
|
rendering operations within the physical target pixel storage that fall
|
|
within the bounds of the window. In a system with a single frame buffer
|
|
holding all windows, this means that damage will accumulate for all
|
|
rendering operations that lie within the visible part of the window.
|
|
|
|
The precise reason for this architecture is to enable the Composite
|
|
extension which provides multiple pixel storage areas for the screen
|
|
contents.
|
|
|
|
3.1 Additions in the 1.1 version of the protocol
|
|
|
|
Damage is automatically computed by the X Server for X rendering operations,
|
|
but direct rendering extensions have allowed clients to perform rendering
|
|
outside of the control of the X Server. The 1.1 version of the protocol
|
|
added a request to allow direct rendering clients to report damage to a
|
|
drawable. Some direct rendering clients, due to architectural limitations,
|
|
always perform rendering to the root window, even in when it should be
|
|
performed to the backing pixmap in the Composite case. To provide
|
|
less-incorrect rendering in this cases, the direct rendering client should
|
|
translate its damage region to screen coordinates and report the damage against
|
|
the root window rather than the drawable.
|
|
|
|
4. Data types
|
|
|
|
The "Damage" object holds any accumulated damage region and reflects the
|
|
relationship between the drawable selected for damage notification and the
|
|
drawable for which damage is tracked.
|
|
|
|
5. Errors
|
|
|
|
Damage
|
|
A value for a DAMAGE argument does not name a defined DAMAGE.
|
|
|
|
6. Types
|
|
|
|
DAMAGE 32-bit value (top three bits guaranteed to be zero)
|
|
|
|
DamageReportLevel { DamageReportRawRectangles,
|
|
DamageReportDeltaRectangles,
|
|
DamageReportBoundingBox,
|
|
DamageReportNonEmpty }
|
|
|
|
DamageReportRawRectangles
|
|
|
|
Delivers DamageNotify events each time the screen
|
|
is modified with rectangular bounds that circumscribe
|
|
the damaged area. No attempt to compress out overlapping
|
|
rectangles is made.
|
|
|
|
DamageReportDeltaRectangles
|
|
|
|
Delivers DamageNotify events each time damage occurs
|
|
which is not included in the damage region. The
|
|
reported rectangles include only the changes to that
|
|
area, not the raw damage data.
|
|
|
|
DamageReportBoundingBox
|
|
|
|
Delivers DamageNotify events each time the bounding
|
|
box enclosing the damage region increases in size.
|
|
The reported rectangle encloses the entire damage region,
|
|
not just the changes to that size.
|
|
|
|
DamageReportNonEmpty
|
|
|
|
Delivers a single DamageNotify event each time the
|
|
damage rectangle changes from empty to non-empty, and
|
|
also whenever the result of a DamageSubtract request
|
|
results in a non-empty region.
|
|
|
|
7. Events
|
|
|
|
DamageNotify
|
|
|
|
level: DamageReportLevel
|
|
drawable: Drawable
|
|
damage: DAMAGE
|
|
more: Bool
|
|
timestamp: Timestamp
|
|
area: Rectangle
|
|
drawable-geometry: Rectangle
|
|
|
|
'more' indicates whether there are subsequent damage events
|
|
being delivered immediately as part of a larger damage region
|
|
|
|
8. Extension Initialization
|
|
|
|
The client must negotiate the version of the extension before executing
|
|
extension requests. Otherwise, the server will return BadRequest for any
|
|
operations other than QueryVersion.
|
|
|
|
QueryVersion
|
|
|
|
client-major-version: CARD32
|
|
client-minor-version: CARD32
|
|
|
|
->
|
|
|
|
major-version: CARD32
|
|
minor-version: CARD32
|
|
|
|
The client sends the highest supported version to the server and
|
|
the server sends the highest version it supports, but no higher than
|
|
the requested version. Major versions changes can introduce
|
|
incompatibilities in existing functionality, minor version
|
|
changes introduce only backward compatible changes. It is
|
|
the clients responsibility to ensure that the server supports
|
|
a version which is compatible with its expectations. Servers
|
|
are encouraged to support multiple versions of the extension.
|
|
|
|
9. Enable Monitoring
|
|
|
|
DamageCreate
|
|
|
|
damage: DAMAGE
|
|
drawable: Drawable
|
|
level: DamageReportLevel
|
|
|
|
Creates a damage object to monitor changes to Drawable
|
|
|
|
DamageDestroy
|
|
damage: DAMAGE
|
|
|
|
Destroys damage.
|
|
|
|
DamageSubtract
|
|
|
|
damage: DAMAGE
|
|
repair: Region or None
|
|
parts: Region
|
|
|
|
Synchronously modifies the regions in the following manner:
|
|
|
|
If repair is None:
|
|
|
|
1) parts = damage
|
|
2) damage = <empty>
|
|
|
|
Otherwise:
|
|
|
|
1) parts = damage INTERSECT repair
|
|
2) damage = damage - parts
|
|
3) Generate DamageNotify for remaining damage areas
|
|
|
|
DamageAdd
|
|
|
|
drawable: Drawable
|
|
region: Region
|
|
|
|
Reports damage of the region within the given drawable. This may be
|
|
used by direct rendering clients to report damage that the server would
|
|
otherwise be unaware of. The damage region is relative to the origin
|
|
of the drawable.
|
|
|
|
Damage posted in this way will appear in DamageNotify events as normal,
|
|
and also in server internal damage tracking (for shadow framebuffer
|
|
updates, pixmap damage, and other uses).
|