damageproto.txt 7.41 KB
Newer Older
1
			The DAMAGE Extension
2
			Protocol Version 1.1
3
			 Document Revision 1
4
			     2007-01-08
5
			     
Keith Packard's avatar
Keith Packard committed
6 7 8
			    Keith Packard
			  keithp@keithp.com

9 10 11 12
			     Eric Anholt
			   eric@anholt.net
		     Open Source Technology Center
			  Intel Corporation
Keith Packard's avatar
Keith Packard committed
13 14 15 16
1. Introduction

Monitoring the regions affected by rendering has wide-spread use, from
VNC-like systems scraping the screen to screen magnifying applications
17
designed to aid users with limited visual acuity.  The DAMAGE extension is
Keith Packard's avatar
Keith Packard committed
18 19 20
designed to make such applications reasonably efficient in the face of
server-client latency.

Adam Jackson's avatar
Adam Jackson committed
21
2. Acknowledgements
Keith Packard's avatar
Keith Packard committed
22 23 24

As usual, the author had significant input from many people, in particular:

25 26 27
 +	Havoc Pennington who designed and implemented a Damage extension
 	last year which was then lost to the mists of time.
			    
Keith Packard's avatar
Keith Packard committed
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
 +	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.

56
The DAMAGE extension allows applications to either receive the raw
Keith Packard's avatar
Keith Packard committed
57 58 59 60 61 62 63
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
64
complexity of this, the DAMAGE extension allows the server to monitor all
Keith Packard's avatar
Keith Packard committed
65 66 67 68 69
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.

70 71
The precise reason for this architecture is to enable the Composite
extension which provides multiple pixel storage areas for the screen
Keith Packard's avatar
Keith Packard committed
72 73
contents.

74 75 76 77 78 79 80 81 82 83 84 85 86
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.

Keith Packard's avatar
Keith Packard committed
87 88
4. Data types

89 90 91
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.
Keith Packard's avatar
Keith Packard committed
92 93 94

5. Errors

95 96
Damage
	A value for a DAMAGE argument does not name a defined DAMAGE.
Keith Packard's avatar
Keith Packard committed
97 98 99

6. Types

100 101
	DAMAGE		32-bit value (top three bits guaranteed to be zero)
	
Keith Packard's avatar
Keith Packard committed
102 103 104 105 106
	DamageReportLevel		{ DamageReportRawRectangles,
					  DamageReportDeltaRectangles,
					  DamageReportBoundingBox,
					  DamageReportNonEmpty }

107
	    DamageReportRawRectangles
Keith Packard's avatar
Keith Packard committed
108 109 110 111 112 113

		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.

114
	    DamageReportDeltaRectangles
Keith Packard's avatar
Keith Packard committed
115 116 117 118 119 120

		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.

121
	    DamageReportBoundingBox
Keith Packard's avatar
Keith Packard committed
122 123 124 125 126 127

		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.

128
	    DamageReportNonEmpty
Keith Packard's avatar
Keith Packard committed
129 130 131 132 133 134 135 136 137 138 139

		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
140 141 142
	drawable:			Drawable
	damage:				DAMAGE
	more:				Bool
Keith Packard's avatar
Keith Packard committed
143
	timestamp:			Timestamp
144 145 146 147 148
	area:				Rectangle
	drawable-geometry:		Rectangle

	'more' indicates whether there are subsequent damage events
	being delivered immediately as part of a larger damage region
Keith Packard's avatar
Keith Packard committed
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176

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

177
DamageCreate
Keith Packard's avatar
Keith Packard committed
178

179 180
		damage:				DAMAGE
		drawable:			Drawable
Keith Packard's avatar
Keith Packard committed
181
		level:				DamageReportLevel
182 183
		
	Creates a damage object to monitor changes to Drawable
Keith Packard's avatar
Keith Packard committed
184

185 186 187 188
DamageDestroy
		damage:				DAMAGE

	Destroys damage.
Keith Packard's avatar
Keith Packard committed
189 190 191

DamageSubtract

192 193
		damage:				DAMAGE
		repair:				Region or None
194
		parts:				Region or None
Keith Packard's avatar
Keith Packard committed
195 196 197

	Synchronously modifies the regions in the following manner:

198
	    If repair is None:
Keith Packard's avatar
Keith Packard committed
199

200
		1)	if parts is not None, parts = damage
201
		2)	damage = <empty>
Keith Packard's avatar
Keith Packard committed
202 203 204
		
	    Otherwise:
	
205 206 207 208
		1)	tmp = damage INTERSECT repair
		2)	damage = damage - tmp
		3)	if parts is not None, parts = tmp
		4)	Generate DamageNotify for remaining damage areas
209

210
DamageAdd
211 212 213 214 215 216

		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
217 218 219 220 221 222
	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).