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