11
Monitoring the regions affected by rendering has wide-spread use, from
12
VNC-like systems scraping the screen to screen magnifying applications
13
designed to aid users with limited visual acuity. The DAMAGE extension is
14
designed to make such applications reasonably efficient in the face of
15
server-client latency.
19
As usual, the author had significant input from many people, in particular:
21
+ Havoc Pennington who designed and implemented a Damage extension
22
last year which was then lost to the mists of time.
24
+ Bill Haneman whose work on accessibility in the Gnome environment
27
+ Jim Gettys who found a way to avoid streaming damage rectangles
28
to the client in many cases.
30
+ Owen Taylor who suggested that streaming damage rectangles may
31
be warranted in some cases after all.
35
We call changes made to pixel contents of windows and pixmaps 'damage'
36
throughout this extension. Another notion of 'damage' are drawable regions
37
which are in need of redisplay to repair the effects of window manipulation
38
or other data loss. This extension doesn't deal with this second notion at
39
all; suggestions on a better term which isn't easily conflated with existing
40
notions are eagerly solicited.
42
Damage accumulates as drawing occurs in the drawable. Each drawing operation
43
'damages' one or more rectangular areas within the drawable. The rectangles
44
are guaranteed to include the set of pixels modified by each operation, but
45
may include significantly more than just those pixels. The desire is for
46
the damage to strike a balance between the number of rectangles reported and
47
the extraneous area included. A reasonable goal is for each primitive
48
object drawn (line, string, rectangle) to be represented as a single
49
rectangle and for the damage area of the operation to be the union of these
52
The DAMAGE extension allows applications to either receive the raw
53
rectangles as a stream of events, or to have them partially processed within
54
the X server to reduce the amount of data transmitted as well as reduce the
55
processing latency once the repaint operation has started.
57
Damage to a window reflects both drawing within the window itself as well as
58
drawing within any inferior window that affects pixels seen by
59
IncludeInferiors rendering operations. To reduce the computational
60
complexity of this, the DAMAGE extension allows the server to monitor all
61
rendering operations within the physical target pixel storage that fall
62
within the bounds of the window. In a system with a single frame buffer
63
holding all windows, this means that damage will accumulate for all
64
rendering operations that lie within the visible part of the window.
66
The precise reason for this architecture will be made clear in the XSPLITTREE
67
extension which will provide multiple pixel storage areas for the screen
72
The "Damage" object holds any accumulated damage region and reflects the
73
relationship between the drawable selected for damage notification and the
74
drawable for which damage is tracked.
79
A value for a DAMAGE argument does not name a defined DAMAGE.
83
DAMAGE 32-bit value (top three bits guaranteed to be zero)
85
DamageReportLevel { DamageReportRawRectangles,
86
DamageReportDeltaRectangles,
87
DamageReportBoundingBox,
88
DamageReportNonEmpty }
90
DamageReportRawRectangles
92
Delivers DamageNotify events each time the screen
93
is modified with rectangular bounds that circumscribe
94
the damaged area. No attempt to compress out overlapping
97
DamageReportDeltaRectangles
99
Delivers DamageNotify events each time damage occurs
100
which is not included in the damage region. The
101
reported rectangles include only the changes to that
102
area, not the raw damage data.
104
DamageReportBoundingBox
106
Delivers DamageNotify events each time the bounding
107
box enclosing the damage region increases in size.
108
The reported rectangle encloses the entire damage region,
109
not just the changes to that size.
113
Delivers a single DamageNotify event each time the
114
damage rectangle changes from empty to non-empty, and
115
also whenever the result of a DamageSubtract request
116
results in a non-empty region.
122
level: DamageReportLevel
128
drawable-geometry: Rectangle
130
'more' indicates whether there are subsequent damage events
131
being delivered immediately as part of a larger damage region
133
8. Extension Initialization
135
The client must negotiate the version of the extension before executing
136
extension requests. Otherwise, the server will return BadRequest for any
137
operations other than QueryVersion.
141
client-major-version: CARD32
142
client-minor-version: CARD32
146
major-version: CARD32
147
minor-version: CARD32
149
The client sends the highest supported version to the server and
150
the server sends the highest version it supports, but no higher than
151
the requested version. Major versions changes can introduce
152
incompatibilities in existing functionality, minor version
153
changes introduce only backward compatible changes. It is
154
the clients responsibility to ensure that the server supports
155
a version which is compatible with its expectations. Servers
156
are encouraged to support multiple versions of the extension.
164
level: DamageReportLevel
166
Creates a damage object to monitor changes to Drawable
176
repair: Region or None
179
Synchronously modifies the regions in the following manner:
188
1) parts = damage INTERSECT repair
189
2) damage = damage - parts
190
3) Generate DamageNotify for remaining damage areas
added
removed
specs/Damage/protocol
