damageproto.txt

   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
  13 1. Introduction
  14
  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.
  20
  21 2. Acknolwedgements
  22
  23 As 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
  37 3.  Damage Model
  38
  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.
  45
  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.
  55
  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.
  60
  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.
  69
  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.
  73
  74 3.1 Additions in the 1.1 version of the protocol
  75
  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.
  86
  87 4. Data types
  88
  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.
  92
  93 5. Errors
  94
  95 Damage
  96         A value for a DAMAGE argument does not name a defined DAMAGE.
  97
  98 6. 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
 135 7. Events
 136
 137 DamageNotify
 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
 150 8. Extension Initialization
 151
 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.
 155
 156 QueryVersion
 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
 175 9. Enable Monitoring
 176
 177 DamageCreate
 178
 179                 damage:                         DAMAGE
 180                 drawable:                       Drawable
 181                 level:                          DamageReportLevel
 182
 183         Creates a damage object to monitor changes to Drawable
 184
 185 DamageDestroy
 186                 damage:                         DAMAGE
 187
 188         Destroys damage.
 189
 190 DamageSubtract
 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
 210 DamageAdd
 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).