qbit/xenocara
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

damageproto 1.1.0

Browse Source
This commit is contained in:
matthieu 2007-09-30 06:41:26 +00:00
parent 61f62dde55
commit 221229ed3e
12 changed files with 367 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
proto/damageproto/AUTHORS Normal file
View File

@ -0,0 +1,2 @@
Keith Packard, HP
Eric Anholt, Intel

27
proto/damageproto/COPYING
View File

@ -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

34
proto/damageproto/ChangeLog
View File

@ -3,7 +3,37 @@
* configure.ac:
Update package version for X11R7 release.
2005-12-14 Kevin E. Martin <kem-at-freedesktop-dot-org>
2005-01-16 Chris Larson <kergoth@handhelds.org>
* configure.ac: Fix to work with automake 1.9.x.
2004-02-03 Jim Gettys <jg@freedesktop.org>
* AUTHORS: Add AUTHORS to file
2004-01-15 Daniel Stone <daniel@fooishbar.org>
* Tag release 1.0 for first freedesktop.org clientside lib release.
2003-11-03 Keith Packard <keithp@keithp.com>
* protocol:
Mark document revision
Credit Havoc the Tolerant for his earlier design and implementation
2003-10-23 Keith Packard <keithp@keithp.com>
* COPYING:
* INSTALL:
* Makefile.am:
* README:
* autogen.sh:
* configure.ac:
Update package version number for final X11R7 release candidate.
* damageext.pc.in:
* damageproto.h:
* damagewire.h:
* protocol:
Initial working version -- added DamageDestroy and damage objects
2003-10-18 Keith Packard <keithp@keithp.com
Initial protocol description added

8
proto/damageproto/INSTALL Normal file
View File

@ -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

29
proto/damageproto/Makefile.am
View File

@ -1,3 +1,26 @@
#
# $Id: Makefile.am,v 1.1.1.2 2007/09/30 06:41:27 matthieu Exp $
#
# Copyright © 2003 Keith Packard, Noah Levitt
#
# 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.
#
# 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.
damagedir = $(includedir)/X11/extensions
damage_HEADERS = \
damageproto.h \
@ -6,4 +29,8 @@ damage_HEADERS = \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = damageproto.pc
EXTRA_DIST = autogen.sh damageproto.pc.in
damagedocdir = $(datadir)/doc/$(PACKAGE)
damagedoc_DATA = damageproto.txt
EXTRA_DIST = autogen.sh damageproto.pc.in $(damagedoc_DATA)

2
proto/damageproto/NEWS Normal file
View File

@ -0,0 +1,2 @@
2004-01-05: Version 1.0 released.
2007-01-09: Version 1.1 released, adding the DamageAdd request.

10
proto/damageproto/README Normal file
View File

@ -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

29
proto/damageproto/configure.ac
View File

@ -1,8 +1,35 @@
dnl
dnl $Id: configure.ac,v 1.1.1.2 2007/09/30 06:41:26 matthieu Exp $
dnl
dnl Copyright © 2003 Keith Packard, Noah Levitt
dnl
dnl Permission to use, copy, modify, distribute, and sell this software and its
dnl documentation for any purpose is hereby granted without fee, provided that
dnl the above copyright notice appear in all copies and that both that
dnl copyright notice and this permission notice appear in supporting
dnl documentation, and that the name of Keith Packard not be used in
dnl advertising or publicity pertaining to distribution of the software without
dnl specific, written prior permission. Keith Packard makes no
dnl representations about the suitability of this software for any purpose. It
dnl is provided "as is" without express or implied warranty.
dnl
dnl KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
dnl INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
dnl EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
dnl CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
dnl DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
dnl TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dnl PERFORMANCE OF THIS SOFTWARE.
dnl
dnl Process this file with autoconf to create configure.
AC_PREREQ([2.57])
AC_INIT([DamageProto], [1.0.3], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AC_INIT([DamageProto], [1.1.0], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AM_INIT_AUTOMAKE([foreign dist-bzip2])
AM_MAINTAINER_MODE
XORG_RELEASE_VERSION
AC_OUTPUT([Makefile
damageproto.pc])

13
proto/damageproto/damageproto.h
View File

@ -1,7 +1,8 @@
/*
* $Id: damageproto.h,v 1.1.1.1 2006/11/25 15:44:45 matthieu Exp $
* $Id: damageproto.h,v 1.1.1.2 2007/09/30 06:41:27 matthieu Exp $
*
* Copyright © 2003 Keith Packard
* Copyright © 2007 Eric Anholt
*
* Permission to use, copy, modify, distribute, and sell this software and its
* documentation for any purpose is hereby granted without fee, provided that
@ -115,6 +116,16 @@ typedef struct {
#define sz_xDamageSubtractReq 16
typedef struct {
CARD8 reqType;
CARD8 damageReqType;
CARD16 length B16;
Drawable drawable B32;
Region region B32;
} xDamageAddReq;
#define sz_xDamageAddReq 12
/* Events */
#define DamageNotifyMore 0x80

221
proto/damageproto/damageproto.txt Normal file
View File

@ -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).

7
proto/damageproto/damagewire.h
View File

@ -1,5 +1,5 @@
/*
* $Id: damagewire.h,v 1.1.1.1 2006/11/25 15:44:45 matthieu Exp $
* $Id: damagewire.h,v 1.1.1.2 2007/09/30 06:41:27 matthieu Exp $
*
* Copyright © 2003 Keith Packard
*
@ -27,7 +27,7 @@
#define DAMAGE_NAME "DAMAGE"
#define DAMAGE_MAJOR 1
#define DAMAGE_MINOR 0
#define DAMAGE_MINOR 1
/************* Version 1 ****************/
@ -42,8 +42,9 @@
#define X_DamageCreate 1
#define X_DamageDestroy 2
#define X_DamageSubtract 3
#define X_DamageAdd 4
#define XDamageNumberRequests (X_DamageSubtract + 1)
#define XDamageNumberRequests (X_DamageAdd + 1)
/* Events */
#define XDamageNotify 0