1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/damageproto.txt	Fri Jan 29 10:23:08 2016 +0200
     1.3 @@ -0,0 +1,222 @@
     1.4 +			The DAMAGE Extension
     1.5 +			Protocol Version 1.1
     1.6 +			 Document Revision 1
     1.7 +			     2007-01-08
     1.8 +			     
     1.9 +			    Keith Packard
    1.10 +			  keithp@keithp.com
    1.11 +
    1.12 +			     Eric Anholt
    1.13 +			   eric@anholt.net
    1.14 +		     Open Source Technology Center
    1.15 +			  Intel Corporation
    1.16 +1. Introduction
    1.17 +
    1.18 +Monitoring the regions affected by rendering has wide-spread use, from
    1.19 +VNC-like systems scraping the screen to screen magnifying applications
    1.20 +designed to aid users with limited visual acuity.  The DAMAGE extension is
    1.21 +designed to make such applications reasonably efficient in the face of
    1.22 +server-client latency.
    1.23 +
    1.24 +2. Acknolwedgements
    1.25 +
    1.26 +As usual, the author had significant input from many people, in particular:
    1.27 +
    1.28 + +	Havoc Pennington who designed and implemented a Damage extension
    1.29 + 	last year which was then lost to the mists of time.
    1.30 +			    
    1.31 + +	Bill Haneman whose work on accessibility in the Gnome environment
    1.32 + 	is legendary.
    1.33 +
    1.34 + +	Jim Gettys who found a way to avoid streaming damage rectangles
    1.35 + 	to the client in many cases.
    1.36 +
    1.37 + +	Owen Taylor who suggested that streaming damage rectangles may
    1.38 + 	be warranted in some cases after all.
    1.39 +
    1.40 +3.  Damage Model
    1.41 +
    1.42 +We call changes made to pixel contents of windows and pixmaps 'damage'
    1.43 +throughout this extension.  Another notion of 'damage' are drawable regions
    1.44 +which are in need of redisplay to repair the effects of window manipulation
    1.45 +or other data loss.  This extension doesn't deal with this second notion at
    1.46 +all; suggestions on a better term which isn't easily conflated with existing
    1.47 +notions are eagerly solicited.
    1.48 +
    1.49 +Damage accumulates as drawing occurs in the drawable.  Each drawing operation
    1.50 +'damages' one or more rectangular areas within the drawable.  The rectangles
    1.51 +are guaranteed to include the set of pixels modified by each operation, but
    1.52 +may include significantly more than just those pixels.  The desire is for
    1.53 +the damage to strike a balance between the number of rectangles reported and
    1.54 +the extraneous area included.  A reasonable goal is for each primitive
    1.55 +object drawn (line, string, rectangle) to be represented as a single
    1.56 +rectangle and for the damage area of the operation to be the union of these
    1.57 +rectangles.
    1.58 +
    1.59 +The DAMAGE extension allows applications to either receive the raw
    1.60 +rectangles as a stream of events, or to have them partially processed within
    1.61 +the X server to reduce the amount of data transmitted as well as reduce the
    1.62 +processing latency once the repaint operation has started.
    1.63 +
    1.64 +Damage to a window reflects both drawing within the window itself as well as
    1.65 +drawing within any inferior window that affects pixels seen by
    1.66 +IncludeInferiors rendering operations.  To reduce the computational
    1.67 +complexity of this, the DAMAGE extension allows the server to monitor all
    1.68 +rendering operations within the physical target pixel storage that fall
    1.69 +within the bounds of the window.  In a system with a single frame buffer
    1.70 +holding all windows, this means that damage will accumulate for all
    1.71 +rendering operations that lie within the visible part of the window.
    1.72 +
    1.73 +The precise reason for this architecture is to enable the Composite
    1.74 +extension which provides multiple pixel storage areas for the screen
    1.75 +contents.
    1.76 +
    1.77 +3.1 Additions in the 1.1 version of the protocol
    1.78 +
    1.79 +Damage is automatically computed by the X Server for X rendering operations,
    1.80 +but direct rendering extensions have allowed clients to perform rendering
    1.81 +outside of the control of the X Server.  The 1.1 version of the protocol
    1.82 +added a request to allow direct rendering clients to report damage to a
    1.83 +drawable.  Some direct rendering clients, due to architectural limitations,
    1.84 +always perform rendering to the root window, even in when it should be
    1.85 +performed to the backing pixmap in the Composite case.  To provide
    1.86 +less-incorrect rendering in this cases, the direct rendering client should
    1.87 +translate its damage region to screen coordinates and report the damage against
    1.88 +the root window rather than the drawable.
    1.89 +
    1.90 +4. Data types
    1.91 +
    1.92 +The "Damage" object holds any accumulated damage region and reflects the
    1.93 +relationship between the drawable selected for damage notification and the
    1.94 +drawable for which damage is tracked.
    1.95 +
    1.96 +5. Errors
    1.97 +
    1.98 +Damage
    1.99 +	A value for a DAMAGE argument does not name a defined DAMAGE.
   1.100 +
   1.101 +6. Types
   1.102 +
   1.103 +	DAMAGE		32-bit value (top three bits guaranteed to be zero)
   1.104 +	
   1.105 +	DamageReportLevel		{ DamageReportRawRectangles,
   1.106 +					  DamageReportDeltaRectangles,
   1.107 +					  DamageReportBoundingBox,
   1.108 +					  DamageReportNonEmpty }
   1.109 +
   1.110 +	    DamageReportRawRectangles
   1.111 +
   1.112 +		Delivers DamageNotify events each time the screen
   1.113 +		is modified with rectangular bounds that circumscribe
   1.114 +		the damaged area.  No attempt to compress out overlapping
   1.115 +		rectangles is made.
   1.116 +
   1.117 +	    DamageReportDeltaRectangles
   1.118 +
   1.119 +		Delivers DamageNotify events each time damage occurs
   1.120 +		which is not included in the damage region.  The
   1.121 +		reported rectangles include only the changes to that
   1.122 +		area, not the raw damage data.
   1.123 +
   1.124 +	    DamageReportBoundingBox
   1.125 +
   1.126 +		Delivers DamageNotify events each time the bounding
   1.127 +		box enclosing the damage region increases in size.
   1.128 +		The reported rectangle encloses the entire damage region,
   1.129 +		not just the changes to that size.
   1.130 +
   1.131 +	    DamageReportNonEmpty
   1.132 +
   1.133 +		Delivers a single DamageNotify event each time the
   1.134 +		damage rectangle changes from empty to non-empty, and
   1.135 +		also whenever the result of a DamageSubtract request
   1.136 +		results in a non-empty region.
   1.137 +
   1.138 +7. Events
   1.139 +
   1.140 +DamageNotify
   1.141 +
   1.142 +	level:				DamageReportLevel
   1.143 +	drawable:			Drawable
   1.144 +	damage:				DAMAGE
   1.145 +	more:				Bool
   1.146 +	timestamp:			Timestamp
   1.147 +	area:				Rectangle
   1.148 +	drawable-geometry:		Rectangle
   1.149 +
   1.150 +	'more' indicates whether there are subsequent damage events
   1.151 +	being delivered immediately as part of a larger damage region
   1.152 +
   1.153 +8. Extension Initialization
   1.154 +
   1.155 +The client must negotiate the version of the extension before executing
   1.156 +extension requests.  Otherwise, the server will return BadRequest for any
   1.157 +operations other than QueryVersion.
   1.158 +
   1.159 +QueryVersion
   1.160 +
   1.161 +		client-major-version:		CARD32
   1.162 +		client-minor-version:		CARD32
   1.163 +
   1.164 +		->
   1.165 +
   1.166 +		major-version:			CARD32
   1.167 +		minor-version:			CARD32
   1.168 +
   1.169 +	The client sends the highest supported version to the server and
   1.170 +	the server sends the highest version it supports, but no higher than
   1.171 +	the requested version.  Major versions changes can introduce
   1.172 +	incompatibilities in existing functionality, minor version
   1.173 +	changes introduce only backward compatible changes.  It is
   1.174 +	the clients responsibility to ensure that the server supports
   1.175 +	a version which is compatible with its expectations.  Servers
   1.176 +	are encouraged to support multiple versions of the extension.
   1.177 +
   1.178 +9. Enable Monitoring
   1.179 +
   1.180 +DamageCreate
   1.181 +
   1.182 +		damage:				DAMAGE
   1.183 +		drawable:			Drawable
   1.184 +		level:				DamageReportLevel
   1.185 +		
   1.186 +	Creates a damage object to monitor changes to Drawable
   1.187 +
   1.188 +DamageDestroy
   1.189 +		damage:				DAMAGE
   1.190 +
   1.191 +	Destroys damage.
   1.192 +
   1.193 +DamageSubtract
   1.194 +
   1.195 +		damage:				DAMAGE
   1.196 +		repair:				Region or None
   1.197 +		parts:				Region or None
   1.198 +
   1.199 +	Synchronously modifies the regions in the following manner:
   1.200 +
   1.201 +	    If repair is None:
   1.202 +
   1.203 +		1)	if parts is not None, parts = damage
   1.204 +		2)	damage = <empty>
   1.205 +		
   1.206 +	    Otherwise:
   1.207 +	
   1.208 +		1)	tmp = damage INTERSECT repair
   1.209 +		2)	damage = damage - tmp
   1.210 +		3)	if parts is not None, parts = tmp
   1.211 +		4)	Generate DamageNotify for remaining damage areas
   1.212 +
   1.213 +DamageAdd
   1.214 +
   1.215 +		drawable:			Drawable
   1.216 +		region:				Region
   1.217 +
   1.218 +	Reports damage of the region within the given drawable.  This may be
   1.219 +	used by direct rendering clients to report damage that the server would
   1.220 +	otherwise be unaware of.  The damage region is relative to the origin
   1.221 +	of the drawable.
   1.222 +
   1.223 +	Damage posted in this way will appear in DamageNotify events as normal,
   1.224 +	and also in server internal damage tracking (for shadow framebuffer
   1.225 +	updates, pixmap damage, and other uses).