qbit/xenocara
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

compositeproto 0.4

Browse Source
This commit is contained in:
matthieu 2007-09-30 06:10:14 +00:00
parent 072724c014
commit b7b575b4ad
12 changed files with 499 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
proto/compositeproto/AUTHORS Normal file
View File

@ -0,0 +1 @@
Keith Packard, HP

2
proto/compositeproto/COPYING
View File

@ -1,4 +1,4 @@
$Id: COPYING,v 1.1.1.1 2006/11/25 15:43:19 matthieu Exp $
$Id: COPYING,v 1.1.1.2 2007/09/30 06:10:16 matthieu Exp $
Copyright © 2003 Keith Packard

84
proto/compositeproto/ChangeLog
View File

@ -1,16 +1,88 @@
2006-04-07 Adam Jackson <ajax@freedesktop.org>
* compositeproto.h:
Bug #1425: Fix the protocol definition on big-endian LP64. (René Rebe)
2006-3-13 Deron Johnson <deron.johnson@sun.com>
2006-3-30 Deron Johnson <deron.johnson@sun.com>
* composite.h
* compositeproto.h
* configure.ac
Composite Version 0.3: CompositeGetOverlayWindow, CompositeReleaseOverlayWindow
Moved Coordinate Transform Redirect defines to 0.4 and bumped request numbers
2005-12-14 Kevin E. Martin <kem-at-freedesktop-dot-org>
* configure.ac:
Update package version number for final X11R7 release candidate.
2004-07-08 Keith Packard <keithp@keithp.com>
* composite.h:
* compositeproto.h:
* protocol:
Add NameWindowPixmap request.
Bump protocol to 0.2
2004-06-27 Eric Anholt <anholt@freedesktop.org>
* protocol:
Fix some apostrophe issues.
2004-02-03 Jim Gettys <freedesktop.org>
* AUTHORS: needed author's attribution
2004-01-15 Daniel Stone <daniel@fooishbar.org>
* Tag release 2.0 for first freedesktop.org clientside release.
2003-11-08 Keith Packard <keithp@keithp.com>
* protocol:
Note that Manual Subwindows mode disables background painting.
2003-11-06 Keith Packard <keithp@keithp.com>
* composite.h:
* compositeproto.h:
Add update mode to Unredirect requests so clients
can redirect multiple times (and then unredirect)
Add CompositeNumberRequests
Fix some typeos
2003-11-04 Keith Packard <keithp@keithp.com>
* COPYING:
* INSTALL:
* Makefile.am:
* README:
* composite.h:
* compositeext.pc.in:
* compositeproto.h:
* configure.ac:
* protocol:
Change name from Apportion to Composite
Clarify that root cannot be redirected.
Add more error values.
2003-10-29 Keith Packard <keithp@keithp.com>
* COPYING:
* INSTALL:
* Makefile.am:
* README:
* apportion.h:
* apportionext.pc.in:
* apportionproto.h:
* autogen.sh:
* configure.ac:
* protocol:
autofoo
Add protocol headers
Use enum for update mode instead of bool
2003-10-29 Keith Packard <keithp@keithp.com>
* protocol:
Define clipping while redirected
2003-10-24 Keith Packard <keithp@keithp.com>
* ChangeLog
* protocol
Initial protocol design imported

8
proto/compositeproto/INSTALL Normal file
View File

@ -0,0 +1,8 @@
CompositeExt is built with the traditional configure script:
$ ./configure --prefix=/usr/X11R6
This should generate valid Makefiles, then:
$ make
$ make install

28
proto/compositeproto/Makefile.am
View File

@ -1,3 +1,26 @@
#
# $Id: Makefile.am,v 1.1.1.2 2007/09/30 06:10:14 matthieu Exp $
#
# Copyright © 2003 Keith Packard, Noah Levitt
#
# Permission to use, copy, modify, distribute, and sell this software and its
# documentation for any purpose is hereby granted without fee, provided that
# the above copyright notice appear in all copies and that both that
# copyright notice and this permission notice appear in supporting
# documentation, and that the name of Keith Packard not be used in
# advertising or publicity pertaining to distribution of the software without
# specific, written prior permission. Keith Packard makes no
# representations about the suitability of this software for any purpose. It
# is provided "as is" without express or implied warranty.
#
# KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
# EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
# DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
# TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
# PERFORMANCE OF THIS SOFTWARE.
compositedir = $(includedir)/X11/extensions
composite_HEADERS = \
composite.h \
@ -6,4 +29,7 @@ composite_HEADERS = \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = compositeproto.pc
EXTRA_DIST = autogen.sh compositeproto.pc.in
compositedocdir = $(datadir)/doc/$(PACKAGE)
compositedoc_DATA = compositeproto.txt
EXTRA_DIST = autogen.sh compositeproto.pc.in $(compositedoc_DATA)

0
proto/compositeproto/NEWS Normal file
View File

9
proto/compositeproto/README Normal file
View File

@ -0,0 +1,9 @@
Composite Extension
Version 0.1
2003-11-04
This package contains header files and documentation for the composite
extension. Library and server implementations are separate.
Keith Packard
keithp@keithp.com

6
proto/compositeproto/composite.h
View File

@ -1,5 +1,5 @@
/*
* $Id: composite.h,v 1.1.1.1 2006/11/25 15:43:21 matthieu Exp $
* $Id: composite.h,v 1.1.1.2 2007/09/30 06:10:14 matthieu Exp $
*
* Copyright © 2006 Sun Microsystems
*
@ -49,7 +49,7 @@
#define COMPOSITE_NAME "Composite"
#define COMPOSITE_MAJOR 0
#define COMPOSITE_MINOR 3
#define COMPOSITE_MINOR 4
#define CompositeRedirectAutomatic 0
#define CompositeRedirectManual 1
@ -66,4 +66,6 @@
#define CompositeNumberRequests (X_CompositeReleaseOverlayWindow + 1)
#define CompositeNumberEvents 0
#endif /* _COMPOSITE_H_ */

5
proto/compositeproto/compositeproto.h
View File

@ -1,5 +1,6 @@
/*
* $Id: compositeproto.h,v 1.1.1.1 2006/11/25 15:43:20 matthieu Exp $
* $Id: compositeproto.h,v 1.1.1.2 2007/09/30 06:10:14 matthieu Exp $
*
*
* Copyright © 2006 Sun Microsystems
*
@ -50,7 +51,6 @@
#define Window CARD32
#define Region CARD32
#define Pixmap CARD32
/*
* requests and replies
@ -187,6 +187,5 @@ typedef struct {
#undef Window
#undef Region
#undef Pixmap
#endif /* _COMPOSITEPROTO_H_ */

4
proto/compositeproto/compositeproto.pc.in
View File

@ -2,8 +2,8 @@ prefix=@prefix@
exec_prefix=@exec_prefix@
libdir=@libdir@
includedir=@includedir@
Name: CompositeProto
Name: CompositeExt
Description: Composite extension headers
Version: @PACKAGE_VERSION@
Cflags: -I${includedir}

339
proto/compositeproto/compositeproto.txt Normal file
View File

@ -0,0 +1,339 @@
Composite Extension
Version 0.4
2007-7-3
Keith Packard
keithp@keithp.com
Deron Johnson
deron.johnson@sun.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.
+ Ryan Lortie for helping figure out reasonable parent clipping
semantics in the presense of manual redirected children.
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.
3.1 NameWindowPixmap
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.
3.2 Composite Overlay Window
Version 0.3 of the protocol adds the Composite Overlay Window, which
provides compositing managers with a surface on which to draw without
interference. This window is always above normal windows and is always
below the screen saver window. It is an InputOutput window whose width
and height are the screen dimensions. Its visual is the root visual
and its border width is zero. Attempts to redirect it using the
composite extension are ignored. This window does not appear in the
reply of the QueryTree request. It is also an override redirect window.
These last two features make it invisible to window managers and other X11
clients. The only way to access the XID of this window is via the
CompositeGetOverlayWindow request. Initially, the Composite Overlay
Window is unmapped.
CompositeGetOverlayWindow returns the XID of the Composite Overlay
Window. If the window has not yet been mapped, it is mapped by this
request. When all clients who have called this request have terminated
their X11 connections the window is unmapped.
Composite managers may render directly to the Composite Overlay
Window, or they may reparent other windows to be children of this
window and render to these. Multiple clients may render to the
Composite Overlay Window, create child windows of it, reshape it, and
redefine its input region, but the specific arbitration rules followed
by these clients is not defined by this specification; these policies
should be defined by the clients themselves.
3.3 Clipping semantics redefined
Version 0.4 of the protocol changes the semantics of clipping in the
presense of manual redirect children. In version 0.3, a parent was always
clipped to child windows, independent of the kind of redirection going on.
With version 0.4, the parent is no longer clipped to child windows which are
manually redirected. This means the parent can draw in the child region without using
IncludeInferiors mode, and (perhaps more importantly), it will receive
expose events in those regions caused by other actions. This new behaviour
is not selectable.
4. Errors
The composite extension does not define any new errors.
5. Types
UPDATETYPE { Automatic, Manual }
CompositeCoordinate
child: Window
x, y: CARD16
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. 'update' specifies whether the contents are mirrored to
the parent window automatically or not. Only one client may specify
an update type of Manual, 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. Composite Overlay Window (0.3 and later)
CompositeGetOverlayWindow
window: Window
->
overlayWin: Window
This request returns the XID of the Composite Overlay Window for
the screen specified by the argument 'window'. This request
indicates that the client wishes to use the Composite Overlay
Window of this screen. If this Composite Overlay Window has not
yet been mapped, it is mapped by this request.
The Composite Overlay Window for a particular screen will be
unmapped when all clients who have invoked this request have
also invoked CompositeReleaseOverlayWindow for that screen. Also,
CompositeReleaseOverlayWindow for a screen will be implicitly
called when a client using the Composite Overlay Window on that
screen terminates its X11 connection.
CompositeReleaseOverlayWindow
window: Window
This request specifies that the client is no longer using the
Composite Overlay Window on the screen specified by the
argument 'window'. A screen's Composite Overlay Window is
unmapped when there are no longer any clients using it.
12. External coordinate transformation (0.4 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.

29
proto/compositeproto/configure.ac
View File

@ -1,8 +1,35 @@
dnl
dnl $Id: configure.ac,v 1.1.1.2 2007/09/30 06:10:14 matthieu Exp $
dnl
dnl Copyright © 2003 Keith Packard, Noah Levitt
dnl
dnl Permission to use, copy, modify, distribute, and sell this software and its
dnl documentation for any purpose is hereby granted without fee, provided that
dnl the above copyright notice appear in all copies and that both that
dnl copyright notice and this permission notice appear in supporting
dnl documentation, and that the name of Keith Packard not be used in
dnl advertising or publicity pertaining to distribution of the software without
dnl specific, written prior permission. Keith Packard makes no
dnl representations about the suitability of this software for any purpose. It
dnl is provided "as is" without express or implied warranty.
dnl
dnl KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
dnl INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
dnl EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
dnl CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
dnl DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
dnl TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dnl PERFORMANCE OF THIS SOFTWARE.
dnl
dnl Process this file with autoconf to create configure.
AC_PREREQ([2.57])
AC_INIT([CompositeProto], [0.3.1], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AC_INIT([CompositeProto], [0.4], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AM_INIT_AUTOMAKE([foreign dist-bzip2])
AM_MAINTAINER_MODE
XORG_RELEASE_VERSION
AC_OUTPUT([Makefile
compositeproto.pc])