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