From ea2c1d120e58e3eb5f2d8eedb3c32b2cfa052366 Mon Sep 17 00:00:00 2001 From: Eric Anholt Date: Tue, 9 Jan 2007 09:46:31 -0800 Subject: Move composite protocol description to the new canonical location/name. --- Makefile.am | 4 +- compositeproto.txt | 292 +++++++++++++++++++++++++++++++++++++++++++++++++++++ protocol | 292 ----------------------------------------------------- 3 files changed, 294 insertions(+), 294 deletions(-) create mode 100644 compositeproto.txt delete mode 100644 protocol diff --git a/Makefile.am b/Makefile.am index eca9e8e..dfc4a1c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -29,7 +29,7 @@ composite_HEADERS = \ pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = compositeproto.pc -compositedocdir = $(datadir)/doc/Composite -compositedoc_DATA = protocol +compositedocdir = $(datadir)/doc/$(PACKAGE) +compositedoc_DATA = compositeproto.txt EXTRA_DIST = autogen.sh compositeproto.pc.in $(compositedoc_DATA) 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. diff --git a/protocol b/protocol deleted file mode 100644 index aab857b..0000000 --- a/protocol +++ /dev/null @@ -1,292 +0,0 @@ - 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. -- cgit v1.2.1