1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/compositeproto.txt	Fri Jan 29 10:23:08 2016 +0200
     1.3 @@ -0,0 +1,339 @@
     1.4 +		         Composite Extension
     1.5 +			     Version 0.4
     1.6 +			      2007-7-3
     1.7 +			    Keith Packard
     1.8 +			  keithp@keithp.com
     1.9 +			    Deron Johnson
    1.10 +     		        deron.johnson@sun.com
    1.11 +
    1.12 +1. Introduction
    1.13 +
    1.14 +Many user interface operations would benefit from having pixel contents of
    1.15 +window hierarchies available without respect to sibling and antecedent
    1.16 +clipping. In addition, placing control over the composition of these pixel
    1.17 +contents into a final screen image in an external application will enable
    1.18 +a flexible system for dynamic application content presentation.
    1.19 +
    1.20 +2. Acknowledgements
    1.21 +
    1.22 +This small extension has been brewing for several years, contributors to
    1.23 +both early prototypes and the final design include:
    1.24 +
    1.25 + +	Bill Haneman for motivating the ability to magnify occluded windows
    1.26 + 	with his work on accessibility
    1.27 +
    1.28 + +	Carsten Haitzler for Enlightenment, the original eye-candy window
    1.29 + 	manager which demonstrated that clever hacks are an awfully
    1.30 +	close substitute for changes in the underlying system.
    1.31 +
    1.32 + +	Jim Gettys for key insights into the relationship between damage
    1.33 + 	events and per-window pixmap usage
    1.34 +
    1.35 + +	Mike Harris and Owen Taylor for figuring out what to call it.
    1.36 +
    1.37 + +	Deron Johnson for the Looking Glass implementation and
    1.38 + 	a prototype of the coordinate transformation mechanism.
    1.39 +
    1.40 + +	Ryan Lortie for helping figure out reasonable parent clipping
    1.41 + 	semantics in the presense of manual redirected children.
    1.42 +
    1.43 +3. Architecture
    1.44 +
    1.45 +The composite extension provides three related mechanisms:
    1.46 +
    1.47 + 1.	Per-hierarchy storage. The rendering of an entire hierarchy of windows
    1.48 + 	is redirected to off-screen storage. The pixels of that hierarchy
    1.49 +	are available whenever it is viewable. Storage is automatically
    1.50 +	reallocated when the top level window changes size. Contents beyond
    1.51 +	the geometry of the top window are not preserved.
    1.52 +
    1.53 + 2.	Automatic shadow update. When a hierarchy is rendered off-screen,
    1.54 + 	the X server provides an automatic mechanism for presenting those
    1.55 +	contents within the parent window. The implementation is free to
    1.56 +	make this update lag behind actual rendering operations by an
    1.57 +	unspecified amount of time. This automatic update mechanism may
    1.58 +	be disabled so that the parent window contents can be completely
    1.59 +	determined by an external application.
    1.60 +
    1.61 + 3.	External parent - child pointer coordinate transformation.
    1.62 + 	When a hierarchy is under manual compositing, the relationship
    1.63 +	of coordinates within the parent to those in the child may
    1.64 +	not be known within the X server. This mechanism provides
    1.65 +	for redirection of these transformations through a client.
    1.66 +
    1.67 +Per-hierarchy storage may be created for individual windows or for all
    1.68 +children of a window. Manual shadow update may be selected by only a single
    1.69 +application for each window; manual update may also be selected on a
    1.70 +per-window basis or for each child of a window. Detecting when to update
    1.71 +may be done with the Damage extension.
    1.72 +
    1.73 +The off-screen storage includes the window contents, its borders and the
    1.74 +contents of all descendants.
    1.75 +
    1.76 +3.1 NameWindowPixmap
    1.77 +
    1.78 +Version 0.2 of the protocol introduces a mechanism for associating an XID
    1.79 +with the off-screen pixmap used to store these contents. This can be used
    1.80 +to hold onto window contents after the window is unmapped (and hence animate
    1.81 +it's disappearance), and also to access the border of the window, which is
    1.82 +not reachable through the Window ID itself. A new pixmap is created each
    1.83 +time the window is mapped or resized; as these events are nicely signalled
    1.84 +with existing events, no additional notification is needed. The old pixmap
    1.85 +will remain allocated as long as the Pixmap ID is left valid, it is
    1.86 +important that the client use the FreePixmap request when it is done with
    1.87 +the contents and to create a new name for the newly allocated pixmap.
    1.88 +
    1.89 +In automatic update mode, the X server is itself responsible for presenting
    1.90 +the child window contents within the parent. It seems reasonable, then, for
    1.91 +rendering to the parent window to be clipped so as not to interfere with any
    1.92 +child window content. In an environment with a mixure of manual and
    1.93 +automatic updating windows, rendering to the parent in the area nominally
    1.94 +occupied by a manual update window should be able to affect parent pixel
    1.95 +values in those areas, but such rendering should be clipped to automatic
    1.96 +update windows, and presumably to other manual update windows managed by
    1.97 +other applications. In any of these cases, it should be easy to ensure that
    1.98 +rendering has no effect on any non-redirected windows.
    1.99 +
   1.100 +Instead of attempting to define new clipping modes for rendering, the
   1.101 +Composite extension instead defines ClipByChildren rendering to the parent
   1.102 +to exclude regions occupied by redirected windows (either automatic or
   1.103 +manual). The CreateRegionFromBorderClip request can be used along with
   1.104 +IncludeInferiors clipping modes to restrict manual shadow updates to the
   1.105 +apporpriate region of the screen. Bracketing operations with
   1.106 +GrabServer/UngrabServer will permit atomic sequences that can update the
   1.107 +screen without artifact. As all of these operations are asynchronous,
   1.108 +network latency should not adversely affect update latency.
   1.109 +
   1.110 +3.2 Composite Overlay Window
   1.111 +
   1.112 +Version 0.3 of the protocol adds the Composite Overlay Window, which
   1.113 +provides compositing managers with a surface on which to draw without
   1.114 +interference. This window is always above normal windows and is always
   1.115 +below the screen saver window. It is an InputOutput window whose width
   1.116 +and height are the screen dimensions. Its visual is the root visual
   1.117 +and its border width is zero.  Attempts to redirect it using the
   1.118 +composite extension are ignored.  This window does not appear in the
   1.119 +reply of the QueryTree request. It is also an override redirect window.
   1.120 +These last two features make it invisible to window managers and other X11
   1.121 +clients. The only way to access the XID of this window is via the
   1.122 +CompositeGetOverlayWindow request. Initially, the Composite Overlay
   1.123 +Window is unmapped.
   1.124 +
   1.125 +CompositeGetOverlayWindow returns the XID of the Composite Overlay
   1.126 +Window. If the window has not yet been mapped, it is mapped by this
   1.127 +request. When all clients who have called this request have terminated
   1.128 +their X11 connections the window is unmapped.
   1.129 +
   1.130 +Composite managers may render directly to the Composite Overlay
   1.131 +Window, or they may reparent other windows to be children of this
   1.132 +window and render to these. Multiple clients may render to the
   1.133 +Composite Overlay Window, create child windows of it, reshape it, and
   1.134 +redefine its input region, but the specific arbitration rules followed
   1.135 +by these clients is not defined by this specification; these policies
   1.136 +should be defined by the clients themselves.
   1.137 +
   1.138 +3.3 Clipping semantics redefined
   1.139 +
   1.140 +Version 0.4 of the protocol changes the semantics of clipping in the
   1.141 +presense of manual redirect children. In version 0.3, a parent was always
   1.142 +clipped to child windows, independent of the kind of redirection going on.
   1.143 +With version 0.4, the parent is no longer clipped to child windows which are
   1.144 +manually redirected. This means the parent can draw in the child region without using
   1.145 +IncludeInferiors mode, and (perhaps more importantly), it will receive
   1.146 +expose events in those regions caused by other actions. This new behaviour
   1.147 +is not selectable.
   1.148 +
   1.149 +4. Errors
   1.150 +
   1.151 +The composite extension does not define any new errors.
   1.152 +
   1.153 +5. Types
   1.154 +
   1.155 +	UPDATETYPE	{ Automatic, Manual }
   1.156 +
   1.157 +	CompositeCoordinate
   1.158 +		child:			Window
   1.159 +		x, y:			CARD16
   1.160 +
   1.161 +7. Extension Initialization
   1.162 +
   1.163 +The client must negotiate the version of the extension before executing
   1.164 +extension requests. Otherwise, the server will return BadRequest for any
   1.165 +operations other than QueryVersion.
   1.166 +
   1.167 +    QueryVersion
   1.168 +
   1.169 +		client-major-version:		CARD32
   1.170 +		client-minor-version:		CARD32
   1.171 +
   1.172 +		->
   1.173 +
   1.174 +		major-version:			CARD32
   1.175 +		minor-version:			CARD32
   1.176 +
   1.177 +	The client sends the highest supported version to the server and
   1.178 +	the server sends the highest version it supports, but no higher than
   1.179 +	the requested version. Major versions changes can introduce
   1.180 +	incompatibilities in existing functionality, minor version
   1.181 +	changes introduce only backward compatible changes. It is
   1.182 +	the client's responsibility to ensure that the server supports
   1.183 +	a version which is compatible with its expectations. Servers
   1.184 +	are encouraged to support multiple versions of the extension.
   1.185 +
   1.186 +8. Hierarchy Redirection
   1.187 +
   1.188 +    RedirectWindow
   1.189 +
   1.190 +		window:				Window
   1.191 +		update:				UPDATETYPE
   1.192 +
   1.193 +		errors: Window, Access, Match
   1.194 +
   1.195 +	The hierarchy starting at 'window' is directed to off-screen
   1.196 +	storage. 'update' specifies whether the contents are mirrored to 
   1.197 +	the parent window automatically or not. Only one client may specify 
   1.198 +	an update type of Manual, another attempt will result in an
   1.199 +	Access error. When all clients enabling redirection terminate,
   1.200 +	the redirection will automatically be disabled.
   1.201 +
   1.202 +	The root window may not be redirected. Doing so results in a Match
   1.203 +	error.
   1.204 +
   1.205 +    RedirectSubwindows
   1.206 +
   1.207 +		window:				Window
   1.208 +		update				UPDATETYPE
   1.209 +
   1.210 +		errors: Window, Access
   1.211 +
   1.212 +	Hierarchies starting at all current and future children of window
   1.213 +	will be redirected as in RedirectWindow. If update is Manual,
   1.214 +	then painting of the window background during window manipulation
   1.215 +	and ClearArea requests is inhibited.
   1.216 +
   1.217 +    UnredirectWindow:
   1.218 +
   1.219 +		window:				Window
   1.220 +
   1.221 +		errors: Window, Value
   1.222 +
   1.223 +	Redirection of the specified window will be terminated. If
   1.224 +	the specified window was not selected for redirection by the
   1.225 +	current client, a 'Value' error results.
   1.226 +
   1.227 +    UnredirectWindows:
   1.228 +
   1.229 +		window:				Window
   1.230 +
   1.231 +		errors: Window, Value
   1.232 +
   1.233 +	Redirection of all children of window will be terminated. If
   1.234 +	the specified window was not selected for sub-redirection by the
   1.235 +	current client, a 'Value' error results.
   1.236 +
   1.237 +9. Clip lists
   1.238 +
   1.239 +    CreateRegionFromBorderClip
   1.240 +
   1.241 +		region:				Region
   1.242 +		window:				Window
   1.243 +
   1.244 +		errors: Window, IDChoice
   1.245 +
   1.246 +	This request creates a region containing the "usual" border clip
   1.247 +	value; that is the area of the window clipped against siblings and
   1.248 +	the parent. This region can be used to restrict rendering to
   1.249 +	suitable areas while updating only a single window. The region
   1.250 +	is copied at the moment the request is executed; future changes
   1.251 +	to the window hierarchy will not be reflected in this region.
   1.252 +
   1.253 +10. Associating a Pixmap ID with the off-screen storage (0.2 and later)
   1.254 +
   1.255 +    NameWindowPixmap
   1.256 +
   1.257 +		window:				Window
   1.258 +		pixmap:				Pixmap
   1.259 +
   1.260 +		errors: Window, Match, IDChoice
   1.261 +
   1.262 +	This request makes 'pixmap' a reference to the off-screen storage
   1.263 +	for 'window'. This pixmap will remain allocated until freed, even
   1.264 +	if 'window' is unmapped, reconfigured or destroyed. However,
   1.265 +	'window' will get a new pixmap allocated each time it is
   1.266 +	mapped or resized, so this request will need to be reinvoked for
   1.267 +	the client to continue to refer to the storage holding the current
   1.268 +	window contents. Generates a 'Match' error if 'window' is not
   1.269 +	redirected or is not visible.
   1.270 +
   1.271 +11. Composite Overlay Window (0.3 and later)
   1.272 +
   1.273 +    CompositeGetOverlayWindow
   1.274 +
   1.275 +	        window:				Window
   1.276 +
   1.277 +	        ->
   1.278 +
   1.279 +	        overlayWin:			Window
   1.280 +
   1.281 +    This request returns the XID of the Composite Overlay Window for 
   1.282 +    the screen specified by the argument 'window'. This request 
   1.283 +    indicates that the client wishes to use the Composite Overlay 
   1.284 +    Window of this screen. If this Composite Overlay Window has not 
   1.285 +    yet been mapped, it is mapped by this request.
   1.286 +
   1.287 +    The Composite Overlay Window for a particular screen will be 
   1.288 +    unmapped when all clients who have invoked this request have 
   1.289 +    also invoked CompositeReleaseOverlayWindow for that screen. Also,
   1.290 +    CompositeReleaseOverlayWindow for a screen will be implicitly 
   1.291 +    called when a client using the Composite Overlay Window on that 
   1.292 +    screen terminates its X11 connection.
   1.293 +
   1.294 +
   1.295 +    CompositeReleaseOverlayWindow
   1.296 +
   1.297 +		window:				Window
   1.298 +
   1.299 +    This request specifies that the client is no longer using the 
   1.300 +    Composite Overlay Window on the screen specified by the 
   1.301 +    argument 'window'. A screen's Composite Overlay Window is 
   1.302 +    unmapped when there are no longer any clients using it.
   1.303 +
   1.304 +12. External coordinate transformation (0.4 and later)
   1.305 +
   1.306 +    RedirectCoordinate
   1.307 +
   1.308 +		window:				Window
   1.309 +		redirect:			BOOL
   1.310 +
   1.311 +		errors: Window, Access
   1.312 +		
   1.313 +	If 'redirect' is TRUE, the requesting client is placed in charge of
   1.314 +	coordinate transformations between 'window' and its children. If
   1.315 +	'redirect' is FALSE, any such redirection is disabled. Any
   1.316 +	transformations needed by the server will be delivered to the
   1.317 +	requesting client in TransformCoordinateNotify events and the
   1.318 +	requesting client must reply with matching TransformCoordinate
   1.319 +	requests for the server to continue with the operation.
   1.320 +
   1.321 +	Generates an 'Access' error if another client has
   1.322 +	redirected coordinates for 'window'.
   1.323 +	
   1.324 +    TransformCoordinate
   1.325 +
   1.326 +		window:				Window
   1.327 +		serialNumber:			CARD32
   1.328 +		x, y:				INT16
   1.329 +		coordinates:			LISTofCompositeCoordinate
   1.330 +
   1.331 +	This provides the transformation data needed by the server for a
   1.332 +	single TransformCoordinateNotify event. 'serialNumber' must match
   1.333 +	the serial number delivered in the event. 'x' and 'y' represent the
   1.334 +	coordinate from the event relative to the 'window'. 'coordinates'
   1.335 +	represent the coordinate from the event relative to each child
   1.336 +	listed. Any children not listed in 'coordinates' are given the
   1.337 +	default transformation using the child window position within the
   1.338 +	parent as a simple translation.
   1.339 +
   1.340 +	The result of this is that any pointer data seen by means of
   1.341 +	the protocol will appear to reflect the transformation
   1.342 +	performed by this request.