Initial revision

ChangeLog

@@ -0,0 +1,3 @@
+2003-10-18	Keith Packard	<keithp@keithp.com
+
+	Initial protocol description added

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