xorg-xorgproto/protocol

			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