summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKeith Packard <keithp@keithp.com>2003-10-19 04:55:31 +0000
committerKeith Packard <keithp@keithp.com>2003-10-19 04:55:31 +0000
commit1b3ffaa1a673418fab22383bf509040924d177d3 (patch)
tree33b1d124099f1a8008a2ecee7bdd30501141b99f
Initial revision
-rw-r--r--ChangeLog3
-rw-r--r--protocol175
2 files changed, 178 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
new file mode 100644
index 0000000..ceab7d9
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1,3 @@
+2003-10-18 Keith Packard <keithp@keithp.com
+
+ Initial protocol description added
diff --git a/protocol b/protocol
new file mode 100644
index 0000000..d3a6a29
--- /dev/null
+++ b/protocol
@@ -0,0 +1,175 @@
+ The XDAMAGE Extension
+ Version 0.0
+ 2003-10-18
+ Keith Packard
+ keithp@keithp.com
+
+1. Introduction
+
+Monitoring the regions affected by rendering has wide-spread use, from
+VNC-like systems scraping the screen to screen magnifying applications
+designed to aid users with limited visual acuity. The XDAMAGE extension is
+designed to make such applications reasonably efficient in the face of
+server-client latency.
+
+2. Acknolwedgements
+
+As usual, the author had significant input from many people, in particular:
+
+ + Bill Haneman whose work on accessibility in the Gnome environment
+ is legendary.
+
+ + Jim Gettys who found a way to avoid streaming damage rectangles
+ to the client in many cases.
+
+ + Owen Taylor who suggested that streaming damage rectangles may
+ be warranted in some cases after all.
+
+3. Damage Model
+
+We call changes made to pixel contents of windows and pixmaps 'damage'
+throughout this extension. Another notion of 'damage' are drawable regions
+which are in need of redisplay to repair the effects of window manipulation
+or other data loss. This extension doesn't deal with this second notion at
+all; suggestions on a better term which isn't easily conflated with existing
+notions are eagerly solicited.
+
+Damage accumulates as drawing occurs in the drawable. Each drawing operation
+'damages' one or more rectangular areas within the drawable. The rectangles
+are guaranteed to include the set of pixels modified by each operation, but
+may include significantly more than just those pixels. The desire is for
+the damage to strike a balance between the number of rectangles reported and
+the extraneous area included. A reasonable goal is for each primitive
+object drawn (line, string, rectangle) to be represented as a single
+rectangle and for the damage area of the operation to be the union of these
+rectangles.
+
+The XDAMAGE extension allows applications to either receive the raw
+rectangles as a stream of events, or to have them partially processed within
+the X server to reduce the amount of data transmitted as well as reduce the
+processing latency once the repaint operation has started.
+
+Damage to a window reflects both drawing within the window itself as well as
+drawing within any inferior window that affects pixels seen by
+IncludeInferiors rendering operations. To reduce the computational
+complexity of this, the XDAMAGE extension allows the server to monitor all
+rendering operations within the physical target pixel storage that fall
+within the bounds of the window. In a system with a single frame buffer
+holding all windows, this means that damage will accumulate for all
+rendering operations that lie within the visible part of the window.
+
+The precise reason for this architecture will be made clear in the XSPLITTREE
+extension which will provide multiple pixel storage areas for the screen
+contents.
+
+4. Data types
+
+The XDAMAGE extension creates no new datatypes itself, but does lean heavily
+on the XFIXES extension region datatypes.
+
+5. Errors
+
+No new errors are included in the XDAMAGE extension.
+
+6. Types
+
+ DamageReportLevel { DamageReportRawRectangles,
+ DamageReportDeltaRectangles,
+ DamageReportBoundingBox,
+ DamageReportNonEmpty }
+
+ DamageReportRawRectangles
+
+ Delivers DamageNotify events each time the screen
+ is modified with rectangular bounds that circumscribe
+ the damaged area. No attempt to compress out overlapping
+ rectangles is made.
+
+ DamageReportDeltaRectangles
+
+ Delivers DamageNotify events each time damage occurs
+ which is not included in the damage region. The
+ reported rectangles include only the changes to that
+ area, not the raw damage data.
+
+ DamageReportBoundingBox
+
+ Delivers DamageNotify events each time the bounding
+ box enclosing the damage region increases in size.
+ The reported rectangle encloses the entire damage region,
+ not just the changes to that size.
+
+ DamageReportNonEmpty
+
+ Delivers a single DamageNotify event each time the
+ damage rectangle changes from empty to non-empty, and
+ also whenever the result of a DamageSubtract request
+ results in a non-empty region.
+
+7. Events
+
+DamageNotify
+
+ level: DamageReportLevel
+ window: Window
+ timestamp: Timestamp
+ damage: Rectangle
+
+8. Extension Initialization
+
+The client must negotiate the version of the extension before executing
+extension requests. Otherwise, the server will return BadRequest for any
+operations other than QueryVersion.
+
+QueryVersion
+
+ client-major-version: CARD32
+ client-minor-version: CARD32
+
+ ->
+
+ major-version: CARD32
+ minor-version: CARD32
+
+ The client sends the highest supported version to the server and
+ the server sends the highest version it supports, but no higher than
+ the requested version. Major versions changes can introduce
+ incompatibilities in existing functionality, minor version
+ changes introduce only backward compatible changes. It is
+ the clients responsibility to ensure that the server supports
+ a version which is compatible with its expectations. Servers
+ are encouraged to support multiple versions of the extension.
+
+9. Enable Monitoring
+
+DamageMonitor
+
+ window: Window
+ level: DamageReportLevel
+ damage_region: Region
+
+ The server establishes a damage monitor for window. 'region'
+ is used to hold the damage region when level is not
+ DamageReportRawRectangles, in which case it is ignored
+ and may be None.
+
+DamageSubtract
+
+ window: window
+ damage_region: Region
+ repair_region: Region or None
+ parts_region: Region
+
+ Synchronously modifies the regions in the following manner:
+
+ If repair_region is None:
+
+ 1) parts_region = damage_region
+ 2) damage_region = <empty>
+
+ Otherwise:
+
+ 1) parts_region = damage_region INTERSECT repair_region
+ 2) damage_region = damage_region - parts_region
+
+