1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
The DAMAGE Extension
Protocol Version 0.0
Document Revision 1
2003-11-03
Keith Packard
keithp@keithp.com
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 will be made clear in the XSPLITTREE
extension which will provide multiple pixel storage areas for the screen
contents.
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
|
