| rev |
line source |
|
nuclear@6
|
1 The DAMAGE Extension
|
|
nuclear@6
|
2 Protocol Version 1.1
|
|
nuclear@6
|
3 Document Revision 1
|
|
nuclear@6
|
4 2007-01-08
|
|
nuclear@6
|
5
|
|
nuclear@6
|
6 Keith Packard
|
|
nuclear@6
|
7 keithp@keithp.com
|
|
nuclear@6
|
8
|
|
nuclear@6
|
9 Eric Anholt
|
|
nuclear@6
|
10 eric@anholt.net
|
|
nuclear@6
|
11 Open Source Technology Center
|
|
nuclear@6
|
12 Intel Corporation
|
|
nuclear@6
|
13 1. Introduction
|
|
nuclear@6
|
14
|
|
nuclear@6
|
15 Monitoring the regions affected by rendering has wide-spread use, from
|
|
nuclear@6
|
16 VNC-like systems scraping the screen to screen magnifying applications
|
|
nuclear@6
|
17 designed to aid users with limited visual acuity. The DAMAGE extension is
|
|
nuclear@6
|
18 designed to make such applications reasonably efficient in the face of
|
|
nuclear@6
|
19 server-client latency.
|
|
nuclear@6
|
20
|
|
nuclear@6
|
21 2. Acknolwedgements
|
|
nuclear@6
|
22
|
|
nuclear@6
|
23 As usual, the author had significant input from many people, in particular:
|
|
nuclear@6
|
24
|
|
nuclear@6
|
25 + Havoc Pennington who designed and implemented a Damage extension
|
|
nuclear@6
|
26 last year which was then lost to the mists of time.
|
|
nuclear@6
|
27
|
|
nuclear@6
|
28 + Bill Haneman whose work on accessibility in the Gnome environment
|
|
nuclear@6
|
29 is legendary.
|
|
nuclear@6
|
30
|
|
nuclear@6
|
31 + Jim Gettys who found a way to avoid streaming damage rectangles
|
|
nuclear@6
|
32 to the client in many cases.
|
|
nuclear@6
|
33
|
|
nuclear@6
|
34 + Owen Taylor who suggested that streaming damage rectangles may
|
|
nuclear@6
|
35 be warranted in some cases after all.
|
|
nuclear@6
|
36
|
|
nuclear@6
|
37 3. Damage Model
|
|
nuclear@6
|
38
|
|
nuclear@6
|
39 We call changes made to pixel contents of windows and pixmaps 'damage'
|
|
nuclear@6
|
40 throughout this extension. Another notion of 'damage' are drawable regions
|
|
nuclear@6
|
41 which are in need of redisplay to repair the effects of window manipulation
|
|
nuclear@6
|
42 or other data loss. This extension doesn't deal with this second notion at
|
|
nuclear@6
|
43 all; suggestions on a better term which isn't easily conflated with existing
|
|
nuclear@6
|
44 notions are eagerly solicited.
|
|
nuclear@6
|
45
|
|
nuclear@6
|
46 Damage accumulates as drawing occurs in the drawable. Each drawing operation
|
|
nuclear@6
|
47 'damages' one or more rectangular areas within the drawable. The rectangles
|
|
nuclear@6
|
48 are guaranteed to include the set of pixels modified by each operation, but
|
|
nuclear@6
|
49 may include significantly more than just those pixels. The desire is for
|
|
nuclear@6
|
50 the damage to strike a balance between the number of rectangles reported and
|
|
nuclear@6
|
51 the extraneous area included. A reasonable goal is for each primitive
|
|
nuclear@6
|
52 object drawn (line, string, rectangle) to be represented as a single
|
|
nuclear@6
|
53 rectangle and for the damage area of the operation to be the union of these
|
|
nuclear@6
|
54 rectangles.
|
|
nuclear@6
|
55
|
|
nuclear@6
|
56 The DAMAGE extension allows applications to either receive the raw
|
|
nuclear@6
|
57 rectangles as a stream of events, or to have them partially processed within
|
|
nuclear@6
|
58 the X server to reduce the amount of data transmitted as well as reduce the
|
|
nuclear@6
|
59 processing latency once the repaint operation has started.
|
|
nuclear@6
|
60
|
|
nuclear@6
|
61 Damage to a window reflects both drawing within the window itself as well as
|
|
nuclear@6
|
62 drawing within any inferior window that affects pixels seen by
|
|
nuclear@6
|
63 IncludeInferiors rendering operations. To reduce the computational
|
|
nuclear@6
|
64 complexity of this, the DAMAGE extension allows the server to monitor all
|
|
nuclear@6
|
65 rendering operations within the physical target pixel storage that fall
|
|
nuclear@6
|
66 within the bounds of the window. In a system with a single frame buffer
|
|
nuclear@6
|
67 holding all windows, this means that damage will accumulate for all
|
|
nuclear@6
|
68 rendering operations that lie within the visible part of the window.
|
|
nuclear@6
|
69
|
|
nuclear@6
|
70 The precise reason for this architecture is to enable the Composite
|
|
nuclear@6
|
71 extension which provides multiple pixel storage areas for the screen
|
|
nuclear@6
|
72 contents.
|
|
nuclear@6
|
73
|
|
nuclear@6
|
74 3.1 Additions in the 1.1 version of the protocol
|
|
nuclear@6
|
75
|
|
nuclear@6
|
76 Damage is automatically computed by the X Server for X rendering operations,
|
|
nuclear@6
|
77 but direct rendering extensions have allowed clients to perform rendering
|
|
nuclear@6
|
78 outside of the control of the X Server. The 1.1 version of the protocol
|
|
nuclear@6
|
79 added a request to allow direct rendering clients to report damage to a
|
|
nuclear@6
|
80 drawable. Some direct rendering clients, due to architectural limitations,
|
|
nuclear@6
|
81 always perform rendering to the root window, even in when it should be
|
|
nuclear@6
|
82 performed to the backing pixmap in the Composite case. To provide
|
|
nuclear@6
|
83 less-incorrect rendering in this cases, the direct rendering client should
|
|
nuclear@6
|
84 translate its damage region to screen coordinates and report the damage against
|
|
nuclear@6
|
85 the root window rather than the drawable.
|
|
nuclear@6
|
86
|
|
nuclear@6
|
87 4. Data types
|
|
nuclear@6
|
88
|
|
nuclear@6
|
89 The "Damage" object holds any accumulated damage region and reflects the
|
|
nuclear@6
|
90 relationship between the drawable selected for damage notification and the
|
|
nuclear@6
|
91 drawable for which damage is tracked.
|
|
nuclear@6
|
92
|
|
nuclear@6
|
93 5. Errors
|
|
nuclear@6
|
94
|
|
nuclear@6
|
95 Damage
|
|
nuclear@6
|
96 A value for a DAMAGE argument does not name a defined DAMAGE.
|
|
nuclear@6
|
97
|
|
nuclear@6
|
98 6. Types
|
|
nuclear@6
|
99
|
|
nuclear@6
|
100 DAMAGE 32-bit value (top three bits guaranteed to be zero)
|
|
nuclear@6
|
101
|
|
nuclear@6
|
102 DamageReportLevel { DamageReportRawRectangles,
|
|
nuclear@6
|
103 DamageReportDeltaRectangles,
|
|
nuclear@6
|
104 DamageReportBoundingBox,
|
|
nuclear@6
|
105 DamageReportNonEmpty }
|
|
nuclear@6
|
106
|
|
nuclear@6
|
107 DamageReportRawRectangles
|
|
nuclear@6
|
108
|
|
nuclear@6
|
109 Delivers DamageNotify events each time the screen
|
|
nuclear@6
|
110 is modified with rectangular bounds that circumscribe
|
|
nuclear@6
|
111 the damaged area. No attempt to compress out overlapping
|
|
nuclear@6
|
112 rectangles is made.
|
|
nuclear@6
|
113
|
|
nuclear@6
|
114 DamageReportDeltaRectangles
|
|
nuclear@6
|
115
|
|
nuclear@6
|
116 Delivers DamageNotify events each time damage occurs
|
|
nuclear@6
|
117 which is not included in the damage region. The
|
|
nuclear@6
|
118 reported rectangles include only the changes to that
|
|
nuclear@6
|
119 area, not the raw damage data.
|
|
nuclear@6
|
120
|
|
nuclear@6
|
121 DamageReportBoundingBox
|
|
nuclear@6
|
122
|
|
nuclear@6
|
123 Delivers DamageNotify events each time the bounding
|
|
nuclear@6
|
124 box enclosing the damage region increases in size.
|
|
nuclear@6
|
125 The reported rectangle encloses the entire damage region,
|
|
nuclear@6
|
126 not just the changes to that size.
|
|
nuclear@6
|
127
|
|
nuclear@6
|
128 DamageReportNonEmpty
|
|
nuclear@6
|
129
|
|
nuclear@6
|
130 Delivers a single DamageNotify event each time the
|
|
nuclear@6
|
131 damage rectangle changes from empty to non-empty, and
|
|
nuclear@6
|
132 also whenever the result of a DamageSubtract request
|
|
nuclear@6
|
133 results in a non-empty region.
|
|
nuclear@6
|
134
|
|
nuclear@6
|
135 7. Events
|
|
nuclear@6
|
136
|
|
nuclear@6
|
137 DamageNotify
|
|
nuclear@6
|
138
|
|
nuclear@6
|
139 level: DamageReportLevel
|
|
nuclear@6
|
140 drawable: Drawable
|
|
nuclear@6
|
141 damage: DAMAGE
|
|
nuclear@6
|
142 more: Bool
|
|
nuclear@6
|
143 timestamp: Timestamp
|
|
nuclear@6
|
144 area: Rectangle
|
|
nuclear@6
|
145 drawable-geometry: Rectangle
|
|
nuclear@6
|
146
|
|
nuclear@6
|
147 'more' indicates whether there are subsequent damage events
|
|
nuclear@6
|
148 being delivered immediately as part of a larger damage region
|
|
nuclear@6
|
149
|
|
nuclear@6
|
150 8. Extension Initialization
|
|
nuclear@6
|
151
|
|
nuclear@6
|
152 The client must negotiate the version of the extension before executing
|
|
nuclear@6
|
153 extension requests. Otherwise, the server will return BadRequest for any
|
|
nuclear@6
|
154 operations other than QueryVersion.
|
|
nuclear@6
|
155
|
|
nuclear@6
|
156 QueryVersion
|
|
nuclear@6
|
157
|
|
nuclear@6
|
158 client-major-version: CARD32
|
|
nuclear@6
|
159 client-minor-version: CARD32
|
|
nuclear@6
|
160
|
|
nuclear@6
|
161 ->
|
|
nuclear@6
|
162
|
|
nuclear@6
|
163 major-version: CARD32
|
|
nuclear@6
|
164 minor-version: CARD32
|
|
nuclear@6
|
165
|
|
nuclear@6
|
166 The client sends the highest supported version to the server and
|
|
nuclear@6
|
167 the server sends the highest version it supports, but no higher than
|
|
nuclear@6
|
168 the requested version. Major versions changes can introduce
|
|
nuclear@6
|
169 incompatibilities in existing functionality, minor version
|
|
nuclear@6
|
170 changes introduce only backward compatible changes. It is
|
|
nuclear@6
|
171 the clients responsibility to ensure that the server supports
|
|
nuclear@6
|
172 a version which is compatible with its expectations. Servers
|
|
nuclear@6
|
173 are encouraged to support multiple versions of the extension.
|
|
nuclear@6
|
174
|
|
nuclear@6
|
175 9. Enable Monitoring
|
|
nuclear@6
|
176
|
|
nuclear@6
|
177 DamageCreate
|
|
nuclear@6
|
178
|
|
nuclear@6
|
179 damage: DAMAGE
|
|
nuclear@6
|
180 drawable: Drawable
|
|
nuclear@6
|
181 level: DamageReportLevel
|
|
nuclear@6
|
182
|
|
nuclear@6
|
183 Creates a damage object to monitor changes to Drawable
|
|
nuclear@6
|
184
|
|
nuclear@6
|
185 DamageDestroy
|
|
nuclear@6
|
186 damage: DAMAGE
|
|
nuclear@6
|
187
|
|
nuclear@6
|
188 Destroys damage.
|
|
nuclear@6
|
189
|
|
nuclear@6
|
190 DamageSubtract
|
|
nuclear@6
|
191
|
|
nuclear@6
|
192 damage: DAMAGE
|
|
nuclear@6
|
193 repair: Region or None
|
|
nuclear@6
|
194 parts: Region or None
|
|
nuclear@6
|
195
|
|
nuclear@6
|
196 Synchronously modifies the regions in the following manner:
|
|
nuclear@6
|
197
|
|
nuclear@6
|
198 If repair is None:
|
|
nuclear@6
|
199
|
|
nuclear@6
|
200 1) if parts is not None, parts = damage
|
|
nuclear@6
|
201 2) damage = <empty>
|
|
nuclear@6
|
202
|
|
nuclear@6
|
203 Otherwise:
|
|
nuclear@6
|
204
|
|
nuclear@6
|
205 1) tmp = damage INTERSECT repair
|
|
nuclear@6
|
206 2) damage = damage - tmp
|
|
nuclear@6
|
207 3) if parts is not None, parts = tmp
|
|
nuclear@6
|
208 4) Generate DamageNotify for remaining damage areas
|
|
nuclear@6
|
209
|
|
nuclear@6
|
210 DamageAdd
|
|
nuclear@6
|
211
|
|
nuclear@6
|
212 drawable: Drawable
|
|
nuclear@6
|
213 region: Region
|
|
nuclear@6
|
214
|
|
nuclear@6
|
215 Reports damage of the region within the given drawable. This may be
|
|
nuclear@6
|
216 used by direct rendering clients to report damage that the server would
|
|
nuclear@6
|
217 otherwise be unaware of. The damage region is relative to the origin
|
|
nuclear@6
|
218 of the drawable.
|
|
nuclear@6
|
219
|
|
nuclear@6
|
220 Damage posted in this way will appear in DamageNotify events as normal,
|
|
nuclear@6
|
221 and also in server internal damage tracking (for shadow framebuffer
|
|
nuclear@6
|
222 updates, pixmap damage, and other uses).
|
