path: root/compositeproto.txt

		        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.