xglcomp

annotate doc/damageproto.txt @ 15:6726f29ebbb8

find changesets by author, revision, files, or words in the commit message
update backing texture on damage
author John Tsiombikas <nuclear@member.fsf.org>
date Mon, 08 Feb 2016 19:42:54 +0200
parents
children
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).