Move composite protocol description to the new canonical location/name.

1 files changed, 292 insertions, 0 deletions

diff --git a/compositeproto.txt b/compositeproto.txt
new file mode 100644
index 0000000..aab857b
--- /dev/null
+++ b/compositeproto.txt
@@ -0,0 +1,292 @@
+		        Composite Extension
+			    Version 0.3
+			      2006-1-22
+			    Keith Packard
+			  keithp@keithp.com
+
+1. Introduction
+
+Many user interface operations would benefit from having pixel contents of
+window hierarchies available without respect to sibling and antecedent
+clipping. In addition, placing control over the composition of these pixel
+contents into a final screen image in an external application will enable
+a flexible system for dynamic application content presentation.
+
+2. Acknowledgements
+
+This small extension has been brewing for several years, contributors to
+both early prototypes and the final design include:
+
+ +	Bill Haneman for motivating the ability to magnify occluded windows
+ 	with his work on accessibility
+
+ +	Carsten Haitzler for Enlightenment, the original eye-candy window
+ 	manager which demonstrated that clever hacks are an awfully
+	close substitute for changes in the underlying system.
+
+ +	Jim Gettys for key insights into the relationship between damage
+ 	events and per-window pixmap usage
+
+ +	Mike Harris and Owen Taylor for figuring out what to call it.
+
+ +	Deron Johnson for the Looking Glass implementation and
+ 	a prototype of the coordinate transformation mechanism.
+
+3. Architecture
+
+The composite extension provides three related mechanisms:
+
+ 1.	Per-hierarchy storage. The rendering of an entire hierarchy of windows
+ 	is redirected to off-screen storage. The pixels of that hierarchy
+	are available whenever it is viewable. Storage is automatically
+	reallocated when the top level window changes size. Contents beyond
+	the geometry of the top window are not preserved.
+
+ 2.	Automatic shadow update. When a hierarchy is rendered off-screen,
+ 	the X server provides an automatic mechanism for presenting those
+	contents within the parent window. The implementation is free to
+	make this update lag behind actual rendering operations by an
+	unspecified amount of time. This automatic update mechanism may
+	be disabled so that the parent window contents can be completely
+	determined by an external application.
+
+ 3.	External parent - child pointer coordinate transformation.
+ 	When a hierarchy is under manual compositing, the relationship
+	of coordinates within the parent to those in the child may
+	not be known within the X server. This mechanism provides
+	for redirection of these transformations through a client.
+
+Per-hierarchy storage may be created for individual windows or for all
+children of a window. Manual shadow update may be selected by only a single
+application for each window; manual update may also be selected on a
+per-window basis or for each child of a window. Detecting when to update
+may be done with the Damage extension.
+
+The off-screen storage includes the window contents, its borders and the
+contents of all descendants.
+
+Version 0.2 of the protocol introduces a mechanism for associating an XID
+with the off-screen pixmap used to store these contents. This can be used
+to hold onto window contents after the window is unmapped (and hence animate
+it's disappearance), and also to access the border of the window, which is
+not reachable through the Window ID itself. A new pixmap is created each
+time the window is mapped or resized; as these events are nicely signalled
+with existing events, no additional notification is needed. The old pixmap
+will remain allocated as long as the Pixmap ID is left valid, it is
+important that the client use the FreePixmap request when it is done with
+the contents and to create a new name for the newly allocated pixmap.
+
+In automatic update mode, the X server is itself responsible for presenting
+the child window contents within the parent. It seems reasonable, then, for
+rendering to the parent window to be clipped so as not to interfere with any
+child window content. In an environment with a mixure of manual and
+automatic updating windows, rendering to the parent in the area nominally
+occupied by a manual update window should be able to affect parent pixel
+values in those areas, but such rendering should be clipped to automatic
+update windows, and presumably to other manual update windows managed by
+other applications. In any of these cases, it should be easy to ensure that
+rendering has no effect on any non-redirected windows.
+
+Instead of attempting to define new clipping modes for rendering, the
+Composite extension instead defines ClipByChildren rendering to the parent
+to exclude regions occupied by redirected windows (either automatic or
+manual). The CreateRegionFromBorderClip request can be used along with
+IncludeInferiors clipping modes to restrict manual shadow updates to the
+apporpriate region of the screen. Bracketing operations with
+GrabServer/UngrabServer will permit atomic sequences that can update the
+screen without artifact. As all of these operations are asynchronous,
+network latency should not adversely affect update latency.
+
+Version 0.3 of the protocol adds the coordinate transformation redirection
+portions of the protocol which externalize the relationship between
+parent and child positions with respect to pointer coordinates.
+
+4. Errors
+
+The composite extension does not define any new errors.
+
+5. Types
+
+	UPDATETYPE	{ Automatic, Manual }
+
+	CompositeCoordinate
+		child:			Window
+		x, y:			CARD16
+
+6. Events
+
+Version 0.3 of the Composite protocol defines one new event
+
+    TransformCoordinateNotify
+    
+		subtype:		COORDINATEEVENT
+		window:			Window
+		child:			Window
+		time:			Timestamp
+		serialNumber:		CARD32
+		count:			CARD32
+		x, y:			INT16
+	
+	This event is delivered to the client requesting for coordinate
+	redirection for 'window'. 'x' and 'y' are a location in 'child' if
+	not None, else in 'window'. 'time' is the time of any related
+	pointer event. 'serialNumber' serves to sequence transformations.
+	'count' indicates the number of events still to be delivered for
+	'window' to satisfy a particular operation within the server
+
+	The client must respond to this event with a suitable
+	TransformCoordinate request that includes matching 'window', 'child'
+	and serialNumber fields.
+
+	'serialNumber' may be repeated in multiple events, indicating that
+	the server needs to redo the same transformation for some reason.
+
+7. 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 client's 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.
+
+8. Hierarchy Redirection
+
+    RedirectWindow
+
+		window:				Window
+		update:				UPDATETYPE
+
+		errors: Window, Access, Match
+
+	The hierarchy starting at 'window' is directed to off-screen
+	storage. 'automatic-update' specifies whether the contents
+	are mirrored to the parent window automatically or not. Only
+	one client may specify this flag, another attempt will result in an
+	Access error. When all clients enabling redirection terminate,
+	the redirection will automatically be disabled.
+
+	The root window may not be redirected. Doing so results in a Match
+	error.
+
+    RedirectSubwindows
+
+		window:				Window
+		update				UPDATETYPE
+
+		errors: Window, Access
+
+	Hierarchies starting at all current and future children of window
+	will be redirected as in RedirectWindow. If update is Manual,
+	then painting of the window background during window manipulation
+	and ClearArea requests is inhibited.
+
+    UnredirectWindow:
+
+		window:				Window
+
+		errors: Window, Value
+
+	Redirection of the specified window will be terminated. If
+	the specified window was not selected for redirection by the
+	current client, a 'Value' error results.
+
+    UnredirectWindows:
+
+		window:				Window
+
+		errors: Window, Value
+
+	Redirection of all children of window will be terminated. If
+	the specified window was not selected for sub-redirection by the
+	current client, a 'Value' error results.
+
+9. Clip lists
+
+    CreateRegionFromBorderClip
+
+		region:				Region
+		window:				Window
+
+		errors: Window, IDChoice
+
+	This request creates a region containing the "usual" border clip
+	value; that is the area of the window clipped against siblings and
+	the parent. This region can be used to restrict rendering to
+	suitable areas while updating only a single window. The region
+	is copied at the moment the request is executed; future changes
+	to the window hierarchy will not be reflected in this region.
+
+10. Associating a Pixmap ID with the off-screen storage (0.2 and later)
+
+    NameWindowPixmap
+
+		window:				Window
+		pixmap:				Pixmap
+
+		errors: Window, Match, IDChoice
+
+	This request makes 'pixmap' a reference to the off-screen storage
+	for 'window'. This pixmap will remain allocated until freed, even
+	if 'window' is unmapped, reconfigured or destroyed. However,
+	'window' will get a new pixmap allocated each time it is
+	mapped or resized, so this request will need to be reinvoked for
+	the client to continue to refer to the storage holding the current
+	window contents. Generates a 'Match' error if 'window' is not
+	redirected or is not visible.
+
+11. External coordinate transformation (0.3 and later)
+
+    RedirectCoordinate
+
+		window:				Window
+		redirect:			BOOL
+
+		errors: Window, Access
+		
+	If 'redirect' is TRUE, the requesting client is placed in charge of
+	coordinate transformations between 'window' and its children. If
+	'redirect' is FALSE, any such redirection is disabled. Any
+	transformations needed by the server will be delivered to the
+	requesting client in TransformCoordinateNotify events and the
+	requesting client must reply with matching TransformCoordinate
+	requests for the server to continue with the operation.
+
+	Generates an 'Access' error if another client has
+	redirected coordinates for 'window'.
+	
+    TransformCoordinate
+
+		window:				Window
+		serialNumber:			CARD32
+		x, y:				INT16
+		coordinates:			LISTofCompositeCoordinate
+
+	This provides the transformation data needed by the server for a
+	single TransformCoordinateNotify event. 'serialNumber' must match
+	the serial number delivered in the event. 'x' and 'y' represent the
+	coordinate from the event relative to the 'window'. 'coordinates'
+	represent the coordinate from the event relative to each child
+	listed. Any children not listed in 'coordinates' are given the
+	default transformation using the child window position within the
+	parent as a simple translation.
+
+	The result of this is that any pointer data seen by means of
+	the protocol will appear to reflect the transformation
+	performed by this request.