diff options
| -rw-r--r-- | proto/damageproto/AUTHORS | 2 | ||||
| -rw-r--r-- | proto/damageproto/COPYING | 27 | ||||
| -rw-r--r-- | proto/damageproto/INSTALL | 8 | ||||
| -rw-r--r-- | proto/damageproto/NEWS | 2 | ||||
| -rw-r--r-- | proto/damageproto/README | 10 | ||||
| -rw-r--r-- | proto/damageproto/damageproto.pc.in | 2 | ||||
| -rw-r--r-- | proto/damageproto/damageproto.txt | 221 |
7 files changed, 263 insertions, 9 deletions
diff --git a/proto/damageproto/AUTHORS b/proto/damageproto/AUTHORS new file mode 100644 index 000000000..78b329f13 --- /dev/null +++ b/proto/damageproto/AUTHORS @@ -0,0 +1,2 @@ +Keith Packard, HP +Eric Anholt, Intel diff --git a/proto/damageproto/COPYING b/proto/damageproto/COPYING index 7f33cbfd2..ca17a4957 100644 --- a/proto/damageproto/COPYING +++ b/proto/damageproto/COPYING @@ -1,12 +1,23 @@ -This is a stub file. This package has not yet had its complete licensing -information compiled. Please see the individual source files for details on -your rights to use and modify this software. +$Id: COPYING,v 1.1.1.2 2007/09/30 06:41:28 matthieu Exp $ -Please submit updated COPYING files to the Xorg bugzilla: +Copyright © 2001,2003 Keith Packard +Copyright © 2007 Eric Anholt -https://bugs.freedesktop.org/enter_bug.cgi?product=xorg +Permission to use, copy, modify, distribute, and sell this software and its +documentation for any purpose is hereby granted without fee, provided that +the above copyright notice appear in all copies and that both that +copyright notice and this permission notice appear in supporting +documentation, and that the name of Keith Packard not be used in +advertising or publicity pertaining to distribution of the software without +specific, written prior permission. Keith Packard makes no +representations about the suitability of this software for any purpose. It +is provided "as is" without express or implied warranty. -All licensing questions regarding this software should be directed at the -Xorg mailing list: +KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO +EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR +CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, +DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER +TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THIS SOFTWARE. -http://lists.freedesktop.org/mailman/listinfo/xorg diff --git a/proto/damageproto/INSTALL b/proto/damageproto/INSTALL new file mode 100644 index 000000000..05868b6d6 --- /dev/null +++ b/proto/damageproto/INSTALL @@ -0,0 +1,8 @@ +Damage is built with the traditional configure script: + + $ ./configure --prefix=/usr/X11R6 + +This should generate valid Makefiles, then: + + $ make + $ make install diff --git a/proto/damageproto/NEWS b/proto/damageproto/NEWS new file mode 100644 index 000000000..29b8edd86 --- /dev/null +++ b/proto/damageproto/NEWS @@ -0,0 +1,2 @@ +2004-01-05: Version 1.0 released. +2007-01-09: Version 1.1 released, adding the DamageAdd request.
\ No newline at end of file diff --git a/proto/damageproto/README b/proto/damageproto/README new file mode 100644 index 000000000..6f1ad4bfc --- /dev/null +++ b/proto/damageproto/README @@ -0,0 +1,10 @@ + Damage + X Damage Extension + Version 1.1 + 2007-01-08 + +This package contains header files and documentation for the X Damage +extension. Library and server implementations are separate. + +Keith Packard +keithp@keithp.com diff --git a/proto/damageproto/damageproto.pc.in b/proto/damageproto/damageproto.pc.in index 8dd9b8918..25476b94f 100644 --- a/proto/damageproto/damageproto.pc.in +++ b/proto/damageproto/damageproto.pc.in @@ -2,7 +2,7 @@ prefix=@prefix@ exec_prefix=@exec_prefix@ libdir=@libdir@ includedir=@includedir@ - + Name: DamageProto Description: Damage extension headers Version: @PACKAGE_VERSION@ diff --git a/proto/damageproto/damageproto.txt b/proto/damageproto/damageproto.txt new file mode 100644 index 000000000..54910adc5 --- /dev/null +++ b/proto/damageproto/damageproto.txt @@ -0,0 +1,221 @@ + The DAMAGE Extension + Protocol Version 1.1 + Document Revision 1 + 2007-01-08 + + Keith Packard + keithp@keithp.com + + Eric Anholt + eric@anholt.net + Open Source Technology Center + Intel Corporation +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 DAMAGE 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: + + + Havoc Pennington who designed and implemented a Damage extension + last year which was then lost to the mists of time. + + + 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 DAMAGE 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 DAMAGE 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 is to enable the Composite +extension which provides multiple pixel storage areas for the screen +contents. + +3.1 Additions in the 1.1 version of the protocol + +Damage is automatically computed by the X Server for X rendering operations, +but direct rendering extensions have allowed clients to perform rendering +outside of the control of the X Server. The 1.1 version of the protocol +added a request to allow direct rendering clients to report damage to a +drawable. Some direct rendering clients, due to architectural limitations, +always perform rendering to the root window, even in when it should be +performed to the backing pixmap in the Composite case. To provide +less-incorrect rendering in this cases, the direct rendering client should +translate its damage region to screen coordinates and report the damage against +the root window rather than the drawable. + +4. Data types + +The "Damage" object holds any accumulated damage region and reflects the +relationship between the drawable selected for damage notification and the +drawable for which damage is tracked. + +5. Errors + +Damage + A value for a DAMAGE argument does not name a defined DAMAGE. + +6. Types + + DAMAGE 32-bit value (top three bits guaranteed to be zero) + + 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 + drawable: Drawable + damage: DAMAGE + more: Bool + timestamp: Timestamp + area: Rectangle + drawable-geometry: Rectangle + + 'more' indicates whether there are subsequent damage events + being delivered immediately as part of a larger damage region + +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 + +DamageCreate + + damage: DAMAGE + drawable: Drawable + level: DamageReportLevel + + Creates a damage object to monitor changes to Drawable + +DamageDestroy + damage: DAMAGE + + Destroys damage. + +DamageSubtract + + damage: DAMAGE + repair: Region or None + parts: Region + + Synchronously modifies the regions in the following manner: + + If repair is None: + + 1) parts = damage + 2) damage = <empty> + + Otherwise: + + 1) parts = damage INTERSECT repair + 2) damage = damage - parts + 3) Generate DamageNotify for remaining damage areas + +DamageAdd + + drawable: Drawable + region: Region + + Reports damage of the region within the given drawable. This may be + used by direct rendering clients to report damage that the server would + otherwise be unaware of. The damage region is relative to the origin + of the drawable. + + Damage posted in this way will appear in DamageNotify events as normal, + and also in server internal damage tracking (for shadow framebuffer + updates, pixmap damage, and other uses). |