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.

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/damageproto.txt	Fri Jan 29 10:23:08 2016 +0200
     2.3 @@ -0,0 +1,222 @@
     2.4 +			The DAMAGE Extension
     2.5 +			Protocol Version 1.1
     2.6 +			 Document Revision 1
     2.7 +			     2007-01-08
     2.8 +			     
     2.9 +			    Keith Packard
    2.10 +			  keithp@keithp.com
    2.11 +
    2.12 +			     Eric Anholt
    2.13 +			   eric@anholt.net
    2.14 +		     Open Source Technology Center
    2.15 +			  Intel Corporation
    2.16 +1. Introduction
    2.17 +
    2.18 +Monitoring the regions affected by rendering has wide-spread use, from
    2.19 +VNC-like systems scraping the screen to screen magnifying applications
    2.20 +designed to aid users with limited visual acuity.  The DAMAGE extension is
    2.21 +designed to make such applications reasonably efficient in the face of
    2.22 +server-client latency.
    2.23 +
    2.24 +2. Acknolwedgements
    2.25 +
    2.26 +As usual, the author had significant input from many people, in particular:
    2.27 +
    2.28 + +	Havoc Pennington who designed and implemented a Damage extension
    2.29 + 	last year which was then lost to the mists of time.
    2.30 +			    
    2.31 + +	Bill Haneman whose work on accessibility in the Gnome environment
    2.32 + 	is legendary.
    2.33 +
    2.34 + +	Jim Gettys who found a way to avoid streaming damage rectangles
    2.35 + 	to the client in many cases.
    2.36 +
    2.37 + +	Owen Taylor who suggested that streaming damage rectangles may
    2.38 + 	be warranted in some cases after all.
    2.39 +
    2.40 +3.  Damage Model
    2.41 +
    2.42 +We call changes made to pixel contents of windows and pixmaps 'damage'
    2.43 +throughout this extension.  Another notion of 'damage' are drawable regions
    2.44 +which are in need of redisplay to repair the effects of window manipulation
    2.45 +or other data loss.  This extension doesn't deal with this second notion at
    2.46 +all; suggestions on a better term which isn't easily conflated with existing
    2.47 +notions are eagerly solicited.
    2.48 +
    2.49 +Damage accumulates as drawing occurs in the drawable.  Each drawing operation
    2.50 +'damages' one or more rectangular areas within the drawable.  The rectangles
    2.51 +are guaranteed to include the set of pixels modified by each operation, but
    2.52 +may include significantly more than just those pixels.  The desire is for
    2.53 +the damage to strike a balance between the number of rectangles reported and
    2.54 +the extraneous area included.  A reasonable goal is for each primitive
    2.55 +object drawn (line, string, rectangle) to be represented as a single
    2.56 +rectangle and for the damage area of the operation to be the union of these
    2.57 +rectangles.
    2.58 +
    2.59 +The DAMAGE extension allows applications to either receive the raw
    2.60 +rectangles as a stream of events, or to have them partially processed within
    2.61 +the X server to reduce the amount of data transmitted as well as reduce the
    2.62 +processing latency once the repaint operation has started.
    2.63 +
    2.64 +Damage to a window reflects both drawing within the window itself as well as
    2.65 +drawing within any inferior window that affects pixels seen by
    2.66 +IncludeInferiors rendering operations.  To reduce the computational
    2.67 +complexity of this, the DAMAGE extension allows the server to monitor all
    2.68 +rendering operations within the physical target pixel storage that fall
    2.69 +within the bounds of the window.  In a system with a single frame buffer
    2.70 +holding all windows, this means that damage will accumulate for all
    2.71 +rendering operations that lie within the visible part of the window.
    2.72 +
    2.73 +The precise reason for this architecture is to enable the Composite
    2.74 +extension which provides multiple pixel storage areas for the screen
    2.75 +contents.
    2.76 +
    2.77 +3.1 Additions in the 1.1 version of the protocol
    2.78 +
    2.79 +Damage is automatically computed by the X Server for X rendering operations,
    2.80 +but direct rendering extensions have allowed clients to perform rendering
    2.81 +outside of the control of the X Server.  The 1.1 version of the protocol
    2.82 +added a request to allow direct rendering clients to report damage to a
    2.83 +drawable.  Some direct rendering clients, due to architectural limitations,
    2.84 +always perform rendering to the root window, even in when it should be
    2.85 +performed to the backing pixmap in the Composite case.  To provide
    2.86 +less-incorrect rendering in this cases, the direct rendering client should
    2.87 +translate its damage region to screen coordinates and report the damage against
    2.88 +the root window rather than the drawable.
    2.89 +
    2.90 +4. Data types
    2.91 +
    2.92 +The "Damage" object holds any accumulated damage region and reflects the
    2.93 +relationship between the drawable selected for damage notification and the
    2.94 +drawable for which damage is tracked.
    2.95 +
    2.96 +5. Errors
    2.97 +
    2.98 +Damage
    2.99 +	A value for a DAMAGE argument does not name a defined DAMAGE.
   2.100 +
   2.101 +6. Types
   2.102 +
   2.103 +	DAMAGE		32-bit value (top three bits guaranteed to be zero)
   2.104 +	
   2.105 +	DamageReportLevel		{ DamageReportRawRectangles,
   2.106 +					  DamageReportDeltaRectangles,
   2.107 +					  DamageReportBoundingBox,
   2.108 +					  DamageReportNonEmpty }
   2.109 +
   2.110 +	    DamageReportRawRectangles
   2.111 +
   2.112 +		Delivers DamageNotify events each time the screen
   2.113 +		is modified with rectangular bounds that circumscribe
   2.114 +		the damaged area.  No attempt to compress out overlapping
   2.115 +		rectangles is made.
   2.116 +
   2.117 +	    DamageReportDeltaRectangles
   2.118 +
   2.119 +		Delivers DamageNotify events each time damage occurs
   2.120 +		which is not included in the damage region.  The
   2.121 +		reported rectangles include only the changes to that
   2.122 +		area, not the raw damage data.
   2.123 +
   2.124 +	    DamageReportBoundingBox
   2.125 +
   2.126 +		Delivers DamageNotify events each time the bounding
   2.127 +		box enclosing the damage region increases in size.
   2.128 +		The reported rectangle encloses the entire damage region,
   2.129 +		not just the changes to that size.
   2.130 +
   2.131 +	    DamageReportNonEmpty
   2.132 +
   2.133 +		Delivers a single DamageNotify event each time the
   2.134 +		damage rectangle changes from empty to non-empty, and
   2.135 +		also whenever the result of a DamageSubtract request
   2.136 +		results in a non-empty region.
   2.137 +
   2.138 +7. Events
   2.139 +
   2.140 +DamageNotify
   2.141 +
   2.142 +	level:				DamageReportLevel
   2.143 +	drawable:			Drawable
   2.144 +	damage:				DAMAGE
   2.145 +	more:				Bool
   2.146 +	timestamp:			Timestamp
   2.147 +	area:				Rectangle
   2.148 +	drawable-geometry:		Rectangle
   2.149 +
   2.150 +	'more' indicates whether there are subsequent damage events
   2.151 +	being delivered immediately as part of a larger damage region
   2.152 +
   2.153 +8. Extension Initialization
   2.154 +
   2.155 +The client must negotiate the version of the extension before executing
   2.156 +extension requests.  Otherwise, the server will return BadRequest for any
   2.157 +operations other than QueryVersion.
   2.158 +
   2.159 +QueryVersion
   2.160 +
   2.161 +		client-major-version:		CARD32
   2.162 +		client-minor-version:		CARD32
   2.163 +
   2.164 +		->
   2.165 +
   2.166 +		major-version:			CARD32
   2.167 +		minor-version:			CARD32
   2.168 +
   2.169 +	The client sends the highest supported version to the server and
   2.170 +	the server sends the highest version it supports, but no higher than
   2.171 +	the requested version.  Major versions changes can introduce
   2.172 +	incompatibilities in existing functionality, minor version
   2.173 +	changes introduce only backward compatible changes.  It is
   2.174 +	the clients responsibility to ensure that the server supports
   2.175 +	a version which is compatible with its expectations.  Servers
   2.176 +	are encouraged to support multiple versions of the extension.
   2.177 +
   2.178 +9. Enable Monitoring
   2.179 +
   2.180 +DamageCreate
   2.181 +
   2.182 +		damage:				DAMAGE
   2.183 +		drawable:			Drawable
   2.184 +		level:				DamageReportLevel
   2.185 +		
   2.186 +	Creates a damage object to monitor changes to Drawable
   2.187 +
   2.188 +DamageDestroy
   2.189 +		damage:				DAMAGE
   2.190 +
   2.191 +	Destroys damage.
   2.192 +
   2.193 +DamageSubtract
   2.194 +
   2.195 +		damage:				DAMAGE
   2.196 +		repair:				Region or None
   2.197 +		parts:				Region or None
   2.198 +
   2.199 +	Synchronously modifies the regions in the following manner:
   2.200 +
   2.201 +	    If repair is None:
   2.202 +
   2.203 +		1)	if parts is not None, parts = damage
   2.204 +		2)	damage = <empty>
   2.205 +		
   2.206 +	    Otherwise:
   2.207 +	
   2.208 +		1)	tmp = damage INTERSECT repair
   2.209 +		2)	damage = damage - tmp
   2.210 +		3)	if parts is not None, parts = tmp
   2.211 +		4)	Generate DamageNotify for remaining damage areas
   2.212 +
   2.213 +DamageAdd
   2.214 +
   2.215 +		drawable:			Drawable
   2.216 +		region:				Region
   2.217 +
   2.218 +	Reports damage of the region within the given drawable.  This may be
   2.219 +	used by direct rendering clients to report damage that the server would
   2.220 +	otherwise be unaware of.  The damage region is relative to the origin
   2.221 +	of the drawable.
   2.222 +
   2.223 +	Damage posted in this way will appear in DamageNotify events as normal,
   2.224 +	and also in server internal damage tracking (for shadow framebuffer
   2.225 +	updates, pixmap damage, and other uses).

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/doc/fixesproto.txt	Fri Jan 29 10:23:08 2016 +0200
     3.3 @@ -0,0 +1,577 @@
     3.4 +                        The XFIXES Extension
     3.5 +			    Version 4.0
     3.6 +			 Document Revision 2
     3.7 +			     2006-12-14
     3.8 +			    Keith Packard
     3.9 +			  keithp@keithp.com
    3.10 +
    3.11 +1. Introduction
    3.12 +
    3.13 +X applications have often needed to work around various shortcomings in the
    3.14 +core X window system.  This extension is designed to provide the minimal
    3.15 +server-side support necessary to eliminate problems caused by these
    3.16 +workarounds.
    3.17 +
    3.18 +2. Acknowledgements
    3.19 +
    3.20 +This extension is a direct result of requests made by application
    3.21 +developers, in particular,
    3.22 +
    3.23 + +	Owen Taylor for describing the issues raised with the XEMBED
    3.24 + 	mechanisms and SaveSet processing and his initial extension
    3.25 +	to handle this issue.
    3.26 +
    3.27 + +	Bill Haneman for the design for cursor image tracking.
    3.28 +
    3.29 + +	Havoc Pennington 
    3.30 +
    3.31 + +	Fredrik Höglund for cursor names
    3.32 +
    3.33 + +	Deron Johnson for cursor visibility
    3.34 +
    3.35 +3. Basic Premise
    3.36 +
    3.37 +Requests in this extension may seem to wander all over the map of X server
    3.38 +capabilities, but they are tied by a simple rule -- resolving issues raised
    3.39 +by application interaction with core protocol mechanisms that cannot be
    3.40 +adequately worked around on the client side of the wire.
    3.41 +
    3.42 +4. Extension initialization
    3.43 +
    3.44 +The client must negotiate the version of the extension before executing
    3.45 +extension requests.  Behavior of the server is undefined otherwise.
    3.46 +
    3.47 +QueryVersion
    3.48 +
    3.49 +	client-major-version:		CARD32
    3.50 +	client-minor-version:		CARD32
    3.51 +
    3.52 +	->
    3.53 +
    3.54 +	major-version:			CARD32
    3.55 +	minor-version:			CARD32
    3.56 +
    3.57 +	The client sends the highest supported version to the server and
    3.58 +	the server sends the highest version it supports, but no higher than
    3.59 +	the requested version.  Major versions changes can introduce
    3.60 +	new requests, minor version changes introduce only adjustments to
    3.61 +	existing requests or backward compatible changes.  It is
    3.62 +	the clients responsibility to ensure that the server supports
    3.63 +	a version which is compatible with its expectations.
    3.64 +
    3.65 +************* XFIXES VERSION 1 OR BETTER ***********
    3.66 +
    3.67 +5. Save Set processing changes
    3.68 +
    3.69 +Embedding one application within another provides a way of unifying
    3.70 +disparate documents and views within a single framework.  From the X
    3.71 +protocol perspective, this appears similar to nested window managers; the
    3.72 +embedding application "manages" the embedded windows much as a window
    3.73 +manager does for top-level windows.  To protect the embedded application
    3.74 +from embedding application failure, it is reasonable to use the core SaveSet
    3.75 +mechanism so that embedding application failure causes embedded windows to
    3.76 +be preserved instead of destroyed.
    3.77 +
    3.78 +The core save set mechanism defines the target for each save set member
    3.79 +window as the nearest enclosing window not owned by the terminating client.
    3.80 +For embedding applications, this nearest window is usually the window
    3.81 +manager frame.  The problem here is that the window manager will not
    3.82 +generally expect to receive and correctly manage new windows appearing within
    3.83 +that window by the save set mechanism, and will instead destroy the frame
    3.84 +window in response to the client window destruction.  This causes the
    3.85 +embedded window to be destroyed.
    3.86 +
    3.87 +An easy fix for this problem is to change the target of the save set member
    3.88 +to a window which won't be affected by the underlying window destruction.
    3.89 +XFIXES chooses the root window as the target.
    3.90 +
    3.91 +Having embedded windows suddenly appear at the top level can confuse users,
    3.92 +so XFIXES also lets the client select whether the window should end up
    3.93 +unmapped after the save set processing instead of unconditionally making
    3.94 +them be mapped.
    3.95 +
    3.96 +5.1 Requests
    3.97 +
    3.98 +ChangeSaveSet
    3.99 +
   3.100 +		window:				Window
   3.101 +		mode:				{ Insert, Delete }
   3.102 +		target:				{ Nearest, Root }
   3.103 +		map:				{ Map, Unmap }
   3.104 +
   3.105 +	ChangeSaveSet is an extension of the core protocol ChangeSaveSet
   3.106 +	request.  As in that request, mode specifies whether the indicated
   3.107 +	window is inserted or deleted from the save-set.  Target specifies
   3.108 +	whether the window is reparented to the nearest non-client window as
   3.109 +	in the core protocol, or reparented to the root window.  Map
   3.110 +	specifies whether the window is mapped as in the core protocol or
   3.111 +	unmapped.
   3.112 +
   3.113 +6. Selection Tracking
   3.114 +
   3.115 +Applications wishing to monitor the contents of current selections must
   3.116 +poll for selection changes.  XFIXES improves this by providing an event
   3.117 +delivered whenever the selection ownership changes.
   3.118 +
   3.119 +6.1 Types
   3.120 +
   3.121 +	SELECTIONEVENT			{ SetSelectionOwner,
   3.122 +					  SelectionWindowDestroy,
   3.123 +					  SelectionClientClose }
   3.124 +
   3.125 +6.1 Events
   3.126 +
   3.127 +SelectionNotify
   3.128 +
   3.129 +	subtype:			SELECTIONEVENT
   3.130 +	window:				Window
   3.131 +	owner:				Window
   3.132 +	selection:			Atom
   3.133 +	timestamp:			Timestamp
   3.134 +	selection-timestamp:		Timestamp
   3.135 +
   3.136 +6.2 Requests
   3.137 +
   3.138 +SelectSelectionInput
   3.139 +
   3.140 +		window:				Window
   3.141 +		selection:			Atom
   3.142 +		event-mask:			SETofSELECTIONEVENT
   3.143 +
   3.144 +	Selects for events to be delivered to window when various causes of
   3.145 +	ownership of selection occur.  Subtype indicates the cause of the
   3.146 +	selection ownership change.  Owner is set to the current selection
   3.147 +	owner, or None.  Timestamp indicates the time the event was
   3.148 +	generated while selection-timestamp indicates the timestamp used to
   3.149 +	own the selection.
   3.150 +
   3.151 +7. Cursor Image Monitoring
   3.152 +
   3.153 +Mirroring the screen contents is easily done with the core protocol or VNC
   3.154 +addons, except for the current cursor image.  There is no way using the core
   3.155 +protocol to discover which cursor image is currently displayed.  The
   3.156 +cursor image often contains significant semantic content about the user
   3.157 +interface.  XFIXES provides a simple mechanism to discover when the cursor
   3.158 +image changes and to fetch the current cursor image.
   3.159 +
   3.160 +As the current cursor may or may not have any XID associated with it, there
   3.161 +is no stable name available.  Instead, XFIXES returns only the image of the
   3.162 +current cursor and provides a way to identify cursor images to avoid
   3.163 +refetching the image each time it changes to a previously seen cursor.
   3.164 +
   3.165 +7.1 Types
   3.166 +	CURSOREVENT			{ DisplayCursor }
   3.167 +
   3.168 +7.2 Events
   3.169 +
   3.170 +CursorNotify
   3.171 +
   3.172 +	subtype:		CURSOREVENT
   3.173 +	window:			Window
   3.174 +	cursor-serial:		CARD32
   3.175 +	timestamp:		Timestamp
   3.176 +	name:			Atom		(Version 2 only)
   3.177 +
   3.178 +7.3 Requests
   3.179 +
   3.180 +SelectCursorInput
   3.181 +
   3.182 +		window:			Window
   3.183 +		event-mask:		SETofCURSOREVENT
   3.184 +
   3.185 +	This request directs cursor change events to the named window.
   3.186 +	Events will be delivered irrespective of the screen on which they
   3.187 +	occur.  Subtype indicates the cause of the cursor image change
   3.188 +	(there is only one subtype at present).  Cursor-serial is a number
   3.189 +	assigned to the cursor image which identifies the image.  Cursors
   3.190 +	with different serial numbers may have different images.  Timestamp
   3.191 +	is the time of the cursor change.
   3.192 +
   3.193 +	Servers supporting the X Input Extension Version 2.0 or higher only
   3.194 +	notify the clients of cursor change events for the ClientPointer, not
   3.195 +	of any other master pointer (see Section 4.4. in the XI2 protocol
   3.196 +	specificiation).
   3.197 +
   3.198 +GetCursorImage
   3.199 +
   3.200 +		->
   3.201 +
   3.202 +		x:			INT16
   3.203 +		y:			INT16
   3.204 +		width:			CARD16
   3.205 +		height:			CARD16
   3.206 +		x-hot:			CARD16
   3.207 +		y-hot:			CARD16
   3.208 +		cursor-serial:		CARD32
   3.209 +		cursor-image:		LISTofCARD32
   3.210 +
   3.211 +	GetCursorImage returns the image of the current cursor.  X and y are
   3.212 +	the current cursor position.  Width and height are the size of the
   3.213 +	cursor image.  X-hot and y-hot mark the hotspot within the cursor
   3.214 +	image.  Cursor-serial provides the number assigned to this cursor
   3.215 +	image, this same serial number will be reported in a CursorNotify
   3.216 +	event if this cursor image is redisplayed in the future.
   3.217 +
   3.218 +	The cursor image itself is returned as a single image at 32 bits per
   3.219 +	pixel with 8 bits of alpha in the most significant 8 bits of the
   3.220 +	pixel followed by 8 bits each of red, green and finally 8 bits of
   3.221 +	blue in the least significant 8 bits.  The color components are
   3.222 +	pre-multiplied with the alpha component.
   3.223 +	
   3.224 +************* XFIXES VERSION 2 OR BETTER ***********
   3.225 +
   3.226 +8. Region Objects
   3.227 +
   3.228 +The core protocol doesn't expose regions as a primitive object and this
   3.229 +makes many operations more complicated than they really need to be.  Adding
   3.230 +region objects simplifies expose handling, the Shape extension and other
   3.231 +operations. These operations are also designed to support a separate
   3.232 +extension, the X Damage Extension.
   3.233 +
   3.234 +8.1 Types
   3.235 +
   3.236 +	Region:				XID
   3.237 +	WINDOW_REGION_KIND:		{ Bounding, Clip }
   3.238 +	
   3.239 +8.2 Errors
   3.240 +
   3.241 +	Region				The specified region is invalid
   3.242 +
   3.243 +8.3 Requests
   3.244 +
   3.245 +CreateRegion
   3.246 +
   3.247 +		region:				REGION
   3.248 +		rects:				LISTofRECTANGLE
   3.249 +
   3.250 +	Creates a region initialized to the specified list of rectangles.
   3.251 +	The rectangles may be specified in any order, their union becomes
   3.252 +	the region.  The core protocol allows applications to specify an
   3.253 +	order for the rectangles, but it turns out to be just as hard to
   3.254 +	verify the rectangles are actually in that order as it is to simply
   3.255 +	ignore the ordering information and union them together.  Hence,
   3.256 +	this request dispenses with the ordering information.
   3.257 +
   3.258 +	Errors: IDChoice
   3.259 +
   3.260 +CreateRegionFromBitmap
   3.261 +
   3.262 +		region:				REGION
   3.263 +		bitmap:				PIXMAP
   3.264 +
   3.265 +	Creates a region initialized to the set of 'one' pixels in bitmap
   3.266 +	(which must be depth 1, else Match error).
   3.267 +
   3.268 +	Errors: Pixmap, IDChoice, Match
   3.269 +
   3.270 +CreateRegionFromWindow
   3.271 +
   3.272 +		window:				Window
   3.273 +		kind:				WINDOW_REGION_KIND
   3.274 +		region:				Region
   3.275 +
   3.276 +	Creates a region initialized to the specified window region.  See the
   3.277 +	Shape extension for the definition of Bounding and Clip regions.
   3.278 +
   3.279 +	Errors: Window, IDChoice, Value
   3.280 +
   3.281 +CreateRegionFromGC
   3.282 +
   3.283 +		gc:				GContext
   3.284 +		region:				Region
   3.285 +
   3.286 +	Creates a region initialized from the clip list of the specified
   3.287 +	GContext.
   3.288 +
   3.289 +	Errors: GContext, IDChoice
   3.290 +
   3.291 +CreateRegionFromPicture
   3.292 +
   3.293 +		picture:			Picture
   3.294 +		region:				Region
   3.295 +
   3.296 +
   3.297 +	Creates a region initialized from the clip list of the specified
   3.298 +	Picture.
   3.299 +
   3.300 +	Errors: Picture, IDChoice
   3.301 +
   3.302 +DestroyRegion
   3.303 +
   3.304 +		region:				Region
   3.305 +
   3.306 +	Destroys the specified region.
   3.307 +
   3.308 +	Errors: Region
   3.309 +
   3.310 +SetRegion
   3.311 +
   3.312 +		region:				Region
   3.313 +		rects:				LISTofRECTANGLE
   3.314 +
   3.315 +	This replaces the current contents of region with the region formed
   3.316 +	by the union of rects.
   3.317 +
   3.318 +CopyRegion
   3.319 +		source:				Region
   3.320 +		destination:			Region
   3.321 +
   3.322 +	This replaces the contents of destination with the contents of 
   3.323 +	source.
   3.324 +
   3.325 +UnionRegion
   3.326 +IntersectRegion
   3.327 +SubtractRegion
   3.328 +
   3.329 +		source1:			Region
   3.330 +		source2:			Region
   3.331 +		destination:			Region
   3.332 +	
   3.333 +	Combines source1 and source2, placing the result in destination.
   3.334 +	Destination may be the same as either source1 or source2.
   3.335 +
   3.336 +	Errors: Region, Value
   3.337 +	
   3.338 +InvertRegion
   3.339 +
   3.340 +		source:				Region
   3.341 +		bounds:				RECTANGLE
   3.342 +		destination:			Region
   3.343 +	
   3.344 +	The source region is subtracted from the region specified by
   3.345 +	bounds.  The result is placed in destination, replacing its contents.
   3.346 +
   3.347 +	Errors: Region
   3.348 +	
   3.349 +TranslateRegion
   3.350 +
   3.351 +		region:				Region
   3.352 +		dx, dy:				INT16
   3.353 +
   3.354 +	The region is translated by dx, dy in place.
   3.355 +
   3.356 +	Errors: Region
   3.357 +
   3.358 +RegionExtents
   3.359 +
   3.360 +		source:				Region
   3.361 +		destination:			Region
   3.362 +
   3.363 +	The extents of the source region are placed in the destination
   3.364 +
   3.365 +FetchRegion
   3.366 +
   3.367 +		region:				Region
   3.368 +		->
   3.369 +		extents:			RECTANGLE
   3.370 +		rectangles:			LISTofRECTANGLE
   3.371 +
   3.372 +	The region is returned as a list of rectangles in YX-banded order.
   3.373 +
   3.374 +	Errors: Region
   3.375 +
   3.376 +SetGCClipRegion
   3.377 +
   3.378 +		gc:				GCONTEXT
   3.379 +		clip-x-origin, clip-y-origin:	INT16
   3.380 +		region:				Region or None
   3.381 +
   3.382 +	This request changes clip-mask in gc to the specified region and
   3.383 +	sets the clip origin.  Output will be clipped to remain contained
   3.384 +	within the region.  The clip origin is interpreted relative to the
   3.385 +	origin of whatever destination drawable is specified in a graphics
   3.386 +	request.  The region is interpreted relative to the clip origin.
   3.387 +	Future changes to region have no effect on the gc clip-mask.
   3.388 +
   3.389 +	Errors: GContext, Region
   3.390 +
   3.391 +SetWindowShapeRegion
   3.392 +
   3.393 +		dest:				Window
   3.394 +		destKind:			SHAPE_KIND
   3.395 +		xOff, yOff:			INT16
   3.396 +		region:				Region or None
   3.397 +
   3.398 +	This request sets the specified (by destKind) Shape extension region
   3.399 +	of the window to region, offset by xOff and yOff.   Future changes to
   3.400 +	region have no effect on the window shape.
   3.401 +
   3.402 +	Errors: Window, Value, Region
   3.403 +
   3.404 +SetPictureClipRegion
   3.405 +
   3.406 +		picture:			Picture
   3.407 +		clip-x-origin, clip-y-origin:	INT16
   3.408 +		region:				Region or None
   3.409 +
   3.410 +	This request changes clip-mask in picture to the specified region
   3.411 +	and sets the clip origin.  Input and output will be clipped to
   3.412 +	remain contained within the region.  The clip origin is interpreted
   3.413 +	relative to the origin of the drawable associated with picture.  The
   3.414 +	region is interpreted relative to the clip origin.  Future changes
   3.415 +	to region have no effect on the picture clip-mask.
   3.416 +
   3.417 +	Errors: Picture, Region
   3.418 +
   3.419 +9. Cursor Names
   3.420 +
   3.421 +Attaching names to cursors permits some abstract semantic content to be
   3.422 +associated with specific cursor images.  Reflecting those names back to
   3.423 +applications allows that semantic content to be related to the user through
   3.424 +non-visual means.
   3.425 +
   3.426 +9.1 Events
   3.427 +
   3.428 +CursorNotify
   3.429 +
   3.430 +		subtype:		CURSOREVENT
   3.431 +		window:			Window
   3.432 +		cursor-serial:		CARD32
   3.433 +		timestamp:		Timestamp
   3.434 +		name:			Atom or None
   3.435 +	
   3.436 +	In Version 2 of the XFIXES protocol, this event adds the atom
   3.437 +	of any name associated with the current cursor (else None).
   3.438 +
   3.439 +9.2 Requests
   3.440 +
   3.441 +SetCursorName
   3.442 +
   3.443 +		cursor:			CURSOR
   3.444 +		name:			LISTofCARD8
   3.445 +
   3.446 +	This request interns name as an atom and sets that atom as the name
   3.447 +	of cursor.
   3.448 +
   3.449 +	Errors: Cursor
   3.450 +
   3.451 +GetCursorName
   3.452 +
   3.453 +		cursor:			CURSOR
   3.454 +		->
   3.455 +		atom:			ATOM or None
   3.456 +		name:			LISTofCARD8
   3.457 +
   3.458 +	This request returns the name and atom of cursor.  If no name is
   3.459 +	set, atom is None and name is empty.
   3.460 +
   3.461 +	Errors: Cursor
   3.462 +
   3.463 +GetCursorImageAndName
   3.464 +
   3.465 +		->
   3.466 +
   3.467 +		x:			INT16
   3.468 +		y:			INT16
   3.469 +		width:			CARD16
   3.470 +		height:			CARD16
   3.471 +		x-hot:			CARD16
   3.472 +		y-hot:			CARD16
   3.473 +		cursor-serial:		CARD32
   3.474 +		cursor-atom:		ATOM
   3.475 +		cursor-name:		LISTofCARD8
   3.476 +		cursor-image:		LISTofCARD32
   3.477 +
   3.478 +	This is similar to GetCursorImage except for including both
   3.479 +	the atom and name of the current cursor.
   3.480 +
   3.481 +ChangeCursor
   3.482 +
   3.483 +		source, destination:	CURSOR
   3.484 +
   3.485 +	This request replaces all references to the destination with a
   3.486 +	reference to source.  Any existing uses of the destination cursor
   3.487 +	object will now show the source cursor image.
   3.488 +
   3.489 +ChangeCursorByName
   3.490 +
   3.491 +		src:			CURSOR
   3.492 +		name:			LISTofCARD8
   3.493 +
   3.494 +	This request replaces the contents of all cursors with the specified
   3.495 +	name with the src cursor.
   3.496 +
   3.497 +************* XFIXES VERSION 3 OR BETTER ***********
   3.498 +
   3.499 +10. Region Expansion
   3.500 +
   3.501 +This update provides another operation on the region objects defined in
   3.502 +Section 8 of this document.
   3.503 +
   3.504 +10.1 Requests
   3.505 +
   3.506 +ExpandRegion
   3.507 +		source:				REGION
   3.508 +		destination:			REGION
   3.509 +		left, right, top, bottom:	CARD16
   3.510 +
   3.511 +	Creates destination region containing the area specified by
   3.512 +	expanding each rectangle in the source region by the specified
   3.513 +	number of pixels to the left, right, top and bottom.
   3.514 +
   3.515 +************* XFIXES VERSION 4 OR BETTER ***********
   3.516 +
   3.517 +11. Cursor Visibility
   3.518 +
   3.519 +Composite managers may want to render the cursor themselves instead of
   3.520 +relying on the X server sprite drawing, this provides a way for them to
   3.521 +do so without getting a double cursor image.
   3.522 +
   3.523 +11.1 Requests
   3.524 +
   3.525 +HideCursor
   3.526 +
   3.527 +		window:			WINDOW
   3.528 +
   3.529 +	A client sends this request to indicate that it wants the
   3.530 +	cursor image to be hidden (i.e. to not be displayed) when
   3.531 +	the sprite is inside the specified window, or one of its
   3.532 +	subwindows. If the sprite is inside a window for which one
   3.533 +	or more active clients have requested cursor hiding then the
   3.534 +	cursor image will not be displayed.
   3.535 +
   3.536 +	Note that even though cursor hiding causes the cursor image
   3.537 +	to be invisible, CursorNotify events will still be sent
   3.538 +	normally, as if the cursor image were visible.
   3.539 +
   3.540 +	If, during a grab, one or more active clients have requested
   3.541 +	cursor hiding for grab window, or one of its ancestors, the
   3.542 +	cursor image of the grab cursor will not be displayed during
   3.543 +	the lifetime of that grab.
   3.544 +
   3.545 +	When a client with outstanding cursor hiding requests
   3.546 +	terminates its connection these requests will be deleted.
   3.547 +
   3.548 +	Servers supporting the X Input Extension Version 2.0 or higher hide
   3.549 +	all visible cursors in response to a HideCursor request. If a master
   3.550 +	pointer is created while the cursors are hidden, this master pointer's
   3.551 +	cursor will be hidden as well.
   3.552 +
   3.553 +ShowCursor
   3.554 +
   3.555 +		window:			WINDOW
   3.556 +
   3.557 +	A client sends this request to indicate that it wants the
   3.558 +	cursor image to be displayed when the sprite is inside the
   3.559 +	specified window, or one of its subwindows. If the sprite
   3.560 +	is inside a window for which no active clients have requested
   3.561 +	cursor hiding then the cursor image for that window will be
   3.562 +	displayed. In other words, if a client calls HideCursor for
   3.563 +	a specified window, or window subtree, this request reverses
   3.564 +	the effects of the HideCursor request.
   3.565 +
   3.566 +	If the client has made no outstanding HideCursor requests
   3.567 +	a BadMatch error is generated.
   3.568 +
   3.569 +	Servers supporting the X Input Extension Version 2.0 or higher show
   3.570 +	all visible cursors in response to a ShowCursor request.
   3.571 +
   3.572 +99. Future compatibility
   3.573 +
   3.574 +This extension is not expected to remain fixed.  Future changes will
   3.575 +strive to remain compatible if at all possible.  The X server will always
   3.576 +support version 1 of the extension protocol if requested by a client.
   3.577 +
   3.578 +Additions to the protocol will always by marked by minor version number
   3.579 +changes so that applications will be able to detect what requests are
   3.580 +supported.

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/doc/texture_from_pixmap.txt	Fri Jan 29 10:23:08 2016 +0200
     4.3 @@ -0,0 +1,792 @@
     4.4 +Name
     4.5 +
     4.6 +    EXT_texture_from_pixmap
     4.7 +
     4.8 +Name Strings
     4.9 +
    4.10 +    GLX_EXT_texture_from_pixmap
    4.11 +
    4.12 +Contributors
    4.13 +
    4.14 +    James Jones, NVIDIA
    4.15 +    Aaron Plattner, NVIDIA
    4.16 +    Andy Ritger, NVIDIA
    4.17 +
    4.18 +Contact
    4.19 +
    4.20 +    David Reveman, Novell, Inc. (davidr 'at' novell.com)
    4.21 +
    4.22 +Status
    4.23 +
    4.24 +    Complete
    4.25 +
    4.26 +Version
    4.27 +
    4.28 +    17 (10 Feb 2009)
    4.29 +
    4.30 +Number
    4.31 +
    4.32 +    344
    4.33 +
    4.34 +Dependencies
    4.35 +
    4.36 +    OpenGL 1.1 is required.
    4.37 +    GLX 1.3 is required.
    4.38 +    GL_EXT_framebuffer_object affects the definition of this extension.
    4.39 +    GL_ARB_texture_rectangle affects the definition of this extension.
    4.40 +    GL_ARB_texture_non_power_of_two affects the definition of this extension.
    4.41 +    GL_SGIS_generate_mipmap affects the definition of this extension.
    4.42 +
    4.43 +Overview
    4.44 +
    4.45 +    This extension allows a color buffer to be used for both rendering and
    4.46 +    texturing.
    4.47 +
    4.48 +    Only color buffers of pixmaps can be used for texturing by this extension
    4.49 +    but other types of drawables can be supported by future extensions layered
    4.50 +    on top of this extension.
    4.51 +
    4.52 +    The functionality of this extension is similar to WGL_ARB_render_texture. 
    4.53 +    However, the purpose of this extension is not to provide
    4.54 +    "render to texture" like functionality but rather the ability to bind
    4.55 +    an existing X drawable to a texture. Though, there is nothing that
    4.56 +    prohibits it from being used for "render to texture".
    4.57 +
    4.58 +    -   Windows are problematic as they can change size and therefore are not
    4.59 +        supported by this extension.
    4.60 +
    4.61 +    -   Only a color buffer of a GLX pixmap created using an FBConfig with
    4.62 +        attribute GLX_BIND_TO_TEXTURE_RGB_EXT or GLX_BIND_TO_TEXTURE_RGBA_EXT
    4.63 +        set to TRUE can be bound as a texture.
    4.64 +
    4.65 +    -   The texture internal format is determined when the color buffer
    4.66 +        is associated with the texture, guaranteeing that the color 
    4.67 +        buffer format is equivalent to the texture internal format.
    4.68 +
    4.69 +    -   A client can create a complete set of mipmap images if
    4.70 +        EXT_framebuffer_object is supported.
    4.71 +
    4.72 +
    4.73 +IP Status 
    4.74 +
    4.75 +    There are no known IP issues. 
    4.76 +
    4.77 +Issues
    4.78 +
    4.79 +    1. What should this extension be called?
    4.80 +
    4.81 +    Even though it is very similar to WGL_ARB_render_texture that name is
    4.82 +    not appropriate as the intention of this extension is not
    4.83 +    "render to texture" like functionality.
    4.84 +
    4.85 +    EXT_texture_from_pixmap seams most appropriate. Layering of future
    4.86 +    extensions on top of this extension for using other type of drawables
    4.87 +    as textures follows the same conventions as vertex/pixel buffer objects
    4.88 +    and vertex/fragment programs.
    4.89 +
    4.90 +
    4.91 +    2. Should we allow applications to render to different mipmap levels and
    4.92 +    cube map faces?
    4.93 +
    4.94 +    In order to discourage the use of this extension as a render to texture
    4.95 +    mechanism, cube maps and rendering directly to mip-map levels > 0 will
    4.96 +    not be supported.  A new FBConfig attribute is introduced that specifies
    4.97 +    whether or not drawables created with that config will support multiple
    4.98 +    mipmap levels when bound to a texture.  The other mipmap levels can be
    4.99 +    filled in by the EXT_framebuffer_object GenerateMipmapEXT function.
   4.100 +
   4.101 +    Specifying which level of a pixmap was being rendered to on a per-drawable
   4.102 +    basis, as was done in the WGL_ARB_render_texture extension, also
   4.103 +    introduces concurrency issues.  The state of the drawable when it was
   4.104 +    being rendered two by two separate threads of execution and both were
   4.105 +    changing the mipmap level was difficult to define.
   4.106 +
   4.107 +    It is also desireable to keep this extension as simple as possible.
   4.108 +    Adding functionality that complicates the implementation and that is not
   4.109 +    directly relevenat to the goal of exposing a mechanism for texturing from
   4.110 +    arbitrary X pixmaps is not productive.  If the ability to render directly
   4.111 +    to all levels of a texture is needed, EXT_framebuffer_object is the
   4.112 +    extension that should be used.
   4.113 +
   4.114 +
   4.115 +    3. Should 1D textures be supported?
   4.116 +
   4.117 +    X servers layered on top of an OpenGL implementation might not be able
   4.118 +    to support this.  A new FBConfig attribute is introduced specifying
   4.119 +    which texture targets a drawable created with the given FBConfig can
   4.120 +    be bound to.
   4.121 +
   4.122 +
   4.123 +    4. What should the default value for GLX_TEXTURE_TARGET_EXT be?  Should
   4.124 +    users be required to set this value if GLX_TEXTURE_FORMAT_EXT is not
   4.125 +    GLX_TEXTURE_FORMAT_NONE_EXT?
   4.126 +
   4.127 +    The implementation is capable of choosing a reasonable default, we simply
   4.128 +    need to specify the correct way to do so.  We can base the ordering on
   4.129 +    the properties of the pixmap and the texturing capabilities of the
   4.130 +    pixmap's FBConfig and the implementation.
   4.131 +
   4.132 +    The order is:
   4.133 +
   4.134 +    - If GL_ARB_texture_non_power_of_two is supported GL_TEXTURE_2D will
   4.135 +      be used for all pixmap sizes.
   4.136 +
   4.137 +    - If only GL_ARB_texture_rectangle is supported GL_TEXTURE_2D will
   4.138 +      be used for all power of two pixmap sizes and GL_TEXTURE_RECTANGLE_ARB
   4.139 +      will be used for all non power of two pixmap sizes.
   4.140 +
   4.141 +
   4.142 +    5. Should users be required to re-bind the drawable to a texture after
   4.143 +    the drawable has been rendered to?
   4.144 +
   4.145 +    It is difficult to define what the contents of the texture would be if
   4.146 +    we don't require this.  Also, requiring this would allow implementations
   4.147 +    to perform an implicit copy at this point if they could not support
   4.148 +    texturing directly out of renderable memory.
   4.149 +
   4.150 +    The problem with defining the contents of the texture after rendering
   4.151 +    has occured to the associated drawable is that there is no way to
   4.152 +    synchronize the use of the buffer as a source and as a destination.
   4.153 +    Direct OpenGL rendering is not necessarily done in the same command
   4.154 +    stream as X rendering.  At the time the pixmap is used as the source
   4.155 +    for a texturing operation, it could be in a state halfway through a
   4.156 +    copyarea operation in which half of it is say, white, and half is the
   4.157 +    result of the copyarea operation.  How is this defined?  Worse, some
   4.158 +    other OpenGL application could be halfway through a frame of rendering
   4.159 +    when the composite manager sources from it.  The buffer might just
   4.160 +    contain the results of a "glClear" operation at that point.
   4.161 +
   4.162 +    To gurantee tear-free rendering, a composite manager would run as follows:
   4.163 +
   4.164 +    -receive request for compositing:
   4.165 +    XGrabServer()
   4.166 +    glXWaitX() or XSync()
   4.167 +    glXBindTexImageEXT()
   4.168 +
   4.169 +    <Do rendering/compositing>
   4.170 +
   4.171 +    glXReleaseTexImageEXT()
   4.172 +    XUngrabServer()
   4.173 +
   4.174 +    Apps that don't synchronize like this would get what's available, 
   4.175 +    and that may or may not be what they expect.
   4.176 +
   4.177 +
   4.178 +    6. What is the result of calling GenerateMipmapEXT on a drawable that
   4.179 +    was not created with mipmap levels?
   4.180 +
   4.181 +    The results are undefined.
   4.182 +
   4.183 +
   4.184 +    7. Rendering done by the window system may be y-inverted compared
   4.185 +    to the standard OpenGL texture representation.  More specifically:
   4.186 +    the X Window system uses a coordinate system where the origin is in
   4.187 +    the upper left; however, the GL uses a coordinate system where the
   4.188 +    origin is in the lower left.  Should we define the contents of the
   4.189 +    texture as the y-inverted contents of the drawable?
   4.190 +
   4.191 +    X implementations may represent their drawables differently internally,
   4.192 +    so y-inversion should be exposed as an FBConfig attribute.
   4.193 +    Applications will need to query this attribute and adjust their rendering
   4.194 +    appropriately.
   4.195 +
   4.196 +    If a drawables is y-inverted and is bound to a texture, the contents of the
   4.197 +    texture will be y-inverted with respect to the standard GL memory layout.
   4.198 +    This means the contents of a pixmap of size (width, height) at pixmap
   4.199 +    coordinate (x, y) will be at location (x, height-y-1) in the texture.
   4.200 +    Applications will need to adjust their texture coordinates accordingly to
   4.201 +    avoid drawing the texture contents upside down.
   4.202 +
   4.203 +
   4.204 +    8. Why wasn't this extension based on FBO instead of ARB_render_texture?
   4.205 +    Isn't the render_texture extension deprecated?
   4.206 +
   4.207 +    At first glance, FBO may seem like the perfect framework to base a spec
   4.208 +    for texturing from pixmap surfaces on.  It replaced the
   4.209 +    WGL_ARB_render_texture specification, which provided a mechanism to
   4.210 +    texture from pbuffer surfaces.  However, this train of thought is another
   4.211 +    side effect of the unfortunate naming of the WGL_ARB_render_texture
   4.212 +    specification.  FBO and the orginal render_texture specification were
   4.213 +    two different solutions to the problem of how to render to and texture
   4.214 +    from the same surface.  WGL_ARB_render_texture provided a method to bind
   4.215 +    a texture to a drawable surface, as this extension does.  FBO provides the
   4.216 +    opposite solution, allowing rendering to arbitrary surfaces including
   4.217 +    textures.  In the case of FBO, the application doing the rendering knows
   4.218 +    that it needs to render to an alternate surface.  In our usage case, the
   4.219 +    application doing the rendering is arbitrary, and has no knowledge that another
   4.220 +    application wants to use the surface it is rendering to as a texture.  The
   4.221 +    only application able to name the surface is the one texturing from it.
   4.222 +    Therefore, it makes sense to provide a mechanism for binding a texture to
   4.223 +    an arbitrary surface in general, and a pixmap in this particular case.
   4.224 +
   4.225 +
   4.226 +    9. Why not allow binding directly to an X pixmap without creating an
   4.227 +    intermediate GLX pixmap?
   4.228 +
   4.229 +    Architecturally, GLX has moved away from operating directly on X
   4.230 +    drawables.  This allows GLX specific attributes to be associated with the
   4.231 +    GLX drawables.  In this case, it is important to associate an FBConfig
   4.232 +    with the drawable.  The FBConfig contains attributes specifying the
   4.233 +    internal format the GL will use when utilizing the drawable's framebuffer
   4.234 +    as a texture.
   4.235 +
   4.236 +
   4.237 +New Procedures and Functions
   4.238 +
   4.239 +    void glXBindTexImageEXT (Display     *display, 
   4.240 +                             GLXDrawable drawable, 
   4.241 +                             int         buffer,
   4.242 +                             const int   *attrib_list)
   4.243 +
   4.244 +    void glXReleaseTexImageEXT (Display     *display, 
   4.245 +                                GLXDrawable drawable, 
   4.246 +                                int         buffer)
   4.247 +
   4.248 +
   4.249 +New Tokens
   4.250 +
   4.251 +    Accepted by the <Attribute> parameter of glXGetFBConfigAttrib and 
   4.252 +    the <attrib_list> parameter of glXChooseFBConfig:
   4.253 +
   4.254 +        GLX_BIND_TO_TEXTURE_RGB_EXT        0x20D0
   4.255 +        GLX_BIND_TO_TEXTURE_RGBA_EXT       0x20D1
   4.256 +        GLX_BIND_TO_MIPMAP_TEXTURE_EXT     0x20D2
   4.257 +        GLX_BIND_TO_TEXTURE_TARGETS_EXT    0x20D3
   4.258 +        GLX_Y_INVERTED_EXT                 0x20D4
   4.259 +
   4.260 +    Accepted as an attribute in the <attrib_list> parameter of
   4.261 +    glXCreatePixmap, and by the <attribute> parameter of glXQueryDrawable:
   4.262 +
   4.263 +        GLX_TEXTURE_FORMAT_EXT             0x20D5
   4.264 +        GLX_TEXTURE_TARGET_EXT             0x20D6
   4.265 +        GLX_MIPMAP_TEXTURE_EXT             0x20D7
   4.266 +
   4.267 +    Accepted as a value in the <attrib_list> parameter of glXCreatePixmap
   4.268 +    and returned in the <value> parameter of glXQueryDrawable when
   4.269 +    <attribute> is GLX_TEXTURE_FORMAT_EXT:
   4.270 +
   4.271 +        GLX_TEXTURE_FORMAT_NONE_EXT        0x20D8
   4.272 +        GLX_TEXTURE_FORMAT_RGB_EXT         0x20D9
   4.273 +        GLX_TEXTURE_FORMAT_RGBA_EXT        0x20DA
   4.274 +
   4.275 +    Accepted as bits in the GLX_BIND_TO_TEXTURE_TARGETS_EXT variable:
   4.276 +
   4.277 +        GLX_TEXTURE_1D_BIT_EXT             0x00000001
   4.278 +        GLX_TEXTURE_2D_BIT_EXT             0x00000002
   4.279 +        GLX_TEXTURE_RECTANGLE_BIT_EXT      0x00000004
   4.280 +
   4.281 +    Accepted as a value in the <attrib_list> parameter of glXCreatePixmap
   4.282 +    and returned in the <value> parameter of glXQueryDrawable when
   4.283 +    <attribute> is GLX_TEXTURE_TARGET_EXT:
   4.284 +
   4.285 +        GLX_TEXTURE_1D_EXT                 0x20DB
   4.286 +        GLX_TEXTURE_2D_EXT                 0x20DC
   4.287 +        GLX_TEXTURE_RECTANGLE_EXT          0x20DD
   4.288 +
   4.289 +    Accepted by the <Buffer> parameter of glXBindTexImageEXT and 
   4.290 +    glXReleaseTexImageEXT: 
   4.291 +
   4.292 +        GLX_FRONT_LEFT_EXT                 0x20DE
   4.293 +        GLX_FRONT_RIGHT_EXT                0x20DF
   4.294 +        GLX_BACK_LEFT_EXT                  0x20E0
   4.295 +        GLX_BACK_RIGHT_EXT                 0x20E1
   4.296 +        GLX_FRONT_EXT                      GLX_FRONT_LEFT_EXT
   4.297 +        GLX_BACK_EXT                       GLX_BACK_LEFT_EXT
   4.298 +        GLX_AUX0_EXT                       0x20E2
   4.299 +        GLX_AUX1_EXT                       0x20E3 
   4.300 +        GLX_AUX2_EXT                       0x20E4 
   4.301 +        GLX_AUX3_EXT                       0x20E5 
   4.302 +        GLX_AUX4_EXT                       0x20E6 
   4.303 +        GLX_AUX5_EXT                       0x20E7 
   4.304 +        GLX_AUX6_EXT                       0x20E8
   4.305 +        GLX_AUX7_EXT                       0x20E9 
   4.306 +        GLX_AUX8_EXT                       0x20EA 
   4.307 +        GLX_AUX9_EXT                       0x20EB
   4.308 +
   4.309 +
   4.310 +GLX Protocol
   4.311 +
   4.312 +    Two new GLX protocol commands are added.
   4.313 +
   4.314 +        BindTexImageEXT
   4.315 +            1           CARD8                   opcode (X assigned)
   4.316 +            1           16                      GLX opcode (glXVendorPrivate)
   4.317 +            2           6+n                     request length
   4.318 +            4           1330                    vendor specific opcode
   4.319 +            4           CARD32                  context tag
   4.320 +            4           GLX_DRAWABLE            drawable
   4.321 +            4           INT32                   buffer
   4.322 +            4           CARD32                  num_attributes
   4.323 +            4*n         LISTofATTRIBUTE_PAIR    attribute, value pairs.
   4.324 +
   4.325 +        ReleaseTexImageEXT
   4.326 +            1           CARD8           opcode (X assigned)
   4.327 +            1           16              GLX opcode (glXVendorPrivate)
   4.328 +            2           5               request length
   4.329 +            4           1331            vendor specific opcode
   4.330 +            4           CARD32          context tag
   4.331 +            4           GLX_DRAWABLE    drawable
   4.332 +            4           INT32           buffer
   4.333 +
   4.334 +
   4.335 +Errors
   4.336 +
   4.337 +Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 
   4.338 +
   4.339 +    None. 
   4.340 +
   4.341 +Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 
   4.342 +
   4.343 +    None. 
   4.344 +
   4.345 +Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 
   4.346 +Operations and the Frame Buffer) 
   4.347 +
   4.348 +    None. 
   4.349 +
   4.350 +Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 
   4.351 +
   4.352 +    None. 
   4.353 +
   4.354 +Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State 
   4.355 +Requests) 
   4.356 +
   4.357 +    None. 
   4.358 +
   4.359 +Additions to the GLX Specification
   4.360 +
   4.361 +    Add to table 3.1, GLXFBConfig Attributes:
   4.362 +
   4.363 +    Attribute                       Type    Notes
   4.364 +    ------------------------------- ------- -------------------------------------------------------------------
   4.365 +    GLX_BIND_TO_TEXTURE_RGB_EXT     boolean True if color buffers can be bound to RGB texture
   4.366 +    GLX_BIND_TO_TEXTURE_RGBA_EXT    boolean True if color buffers can be bound to RGBA texture
   4.367 +    GLX_BIND_TO_MIPMAP_TEXTURE_EXT  boolean True if color buffers can be bound to textures with multiple levels
   4.368 +    GLX_BIND_TO_TEXTURE_TARGETS_EXT bitmask Bitmask of texture targets color buffers can be bound to
   4.369 +    GLX_Y_INVERTED_EXT              boolean True if the drawable's framebuffer is y-inverted.  This can be used to determine if y-inverted texture coordinates need to be used when texturing from this drawable when it is bound to a texture target.
   4.370 +
   4.371 +    Additions to table 3.4, Default Match Criteria for GLXFBConfig attributes:
   4.372 +
   4.373 +    Attribute                       Default              Selection Criteria Priority
   4.374 +    ------------------------------- -------------------- ------------------ ---------
   4.375 +    GLX_BIND_TO_TEXTURE_RGB_EXT     GLX_DONT_CARE        Exact
   4.376 +    GLX_BIND_TO_TEXTURE_RGBA_EXT    GLX_DONT_CARE        Exact
   4.377 +    GLX_BIND_TO_MIPMAP_TEXTURE_EXT  GLX_DONT_CARE        Exact
   4.378 +    GLX_BIND_TO_TEXTURE_TARGETS_EXT -                    Mask
   4.379 +    GLX_Y_INVERTED_EXT              GLX_DONT_CARE        Exact
   4.380 +
   4.381 +    Modifications to 3.3.3, "Configuration Management"
   4.382 +
   4.383 +    Add after paragraph 17 in the description of FBConfigs:
   4.384 +
   4.385 +    GLX_Y_INVERTED_EXT is a boolean describing the memory layout used for
   4.386 +    drawables created with the GLXFBConfig.  The attribute is True if the
   4.387 +    drawable's framebuffer will be y-inverted.  This can be used to determine
   4.388 +    if y-inverted texture coordinates need to be used when texturing from this
   4.389 +    drawable when it is bound to a texture target.
   4.390 +
   4.391 +    Modifications to 3.3.5, "Offscreen Rendering"
   4.392 +
   4.393 +    Modify paragraph 3 of the description of glXCreatePixmap:
   4.394 +
   4.395 +    <attrib_list> specifies a list of attributes for the pixmap.  The list has
   4.396 +    the same structure as described for glXChooseFBConfig.  Currently the
   4.397 +    following attributes can be specified in attrib_list:
   4.398 +    GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT, GLX_MIPMAP_TEXTURE_EXT,
   4.399 +    attrib_list may be NULL or empty (first attribute of None), in which case
   4.400 +    all attributes assume their default values as described below.
   4.401 +
   4.402 +    GLX_TEXTURE_FORMAT_EXT describes the texture format this pixmap can be
   4.403 +    bound to.  Valid values are GLX_TEXTURE_FORMAT_RGB_EXT,
   4.404 +    GLX_TEXTURE_FORMAT_RGBA_EXT, and GLX_TEXTURE_FORMAT_NONE_EXT.
   4.405 +
   4.406 +    GLX_TEXTURE_TARGET_EXT can be set to GLX_TEXTURE_1D_EXT,
   4.407 +    GLX_TEXTURE_2D_EXT, or GLX_TEXTURE_RECTANGLE_EXT; it indicates the type
   4.408 +    of texture that will be created when GLX_TEXTURE_FORMAT_EXT is not
   4.409 +    GLX_TEXTURE_FORMAT_NONE_EXT.  The default value of GLX_TEXTURE_TARGET_EXT
   4.410 +    depends on the capabilities in <config> and the dimensions of the pixmap.
   4.411 +    If <config> has GLX_TEXTURE_2D_BIT set and one or more of the following is
   4.412 +    true:
   4.413 +
   4.414 +        * GLX_TEXTURE_RECTANGLE_BIT_EXT is not set in <config>
   4.415 +
   4.416 +        * GL_ARB_texture_non_power_of_two is supported
   4.417 +
   4.418 +        * the pixmap's width and height are powers of 2
   4.419 +
   4.420 +    the default value for GLX_TEXTURE_TARGET_EXT is GLX_TEXTURE_2D_EXT.
   4.421 +
   4.422 +    Otherwise, the first supported target is chosen in this order:
   4.423 +    GLX_TEXTURE_RECTANGLE_EXT, GLX_TEXTURE_1D_EXT.
   4.424 +
   4.425 +    GLX_MIPMAP_TEXTURE_EXT indicates that storage for mipmaps should be
   4.426 +    allocated.  Space for mipmaps will be set aside if GLX_TEXTURE_FORMAT_EXT
   4.427 +    is not GLX_TEXTURE_FORMAT_NONE_EXT and GLX_MIPMAP_TEXTURE_EXT is TRUE.
   4.428 +    The default value is FALSE.
   4.429 +
   4.430 +    Modify paragraph 5 of the description of glXCreatePixmap:
   4.431 +
   4.432 +    ...If <pixmap> is not a valid Pixmap XID, then a BadPixmap error is
   4.433 +    generated.  A BadConfig error is generated if any of the following
   4.434 +    conditions are true:
   4.435 +
   4.436 +        * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGB_EXT and
   4.437 +          <config> does not have GLX_BIND_TO_TEXTURE_RGB set to TRUE.
   4.438 +
   4.439 +        * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGBA_EXT and
   4.440 +          <config> does not have GLX_BIND_TO_TEXTURE_RGBA set to TRUE.
   4.441 +
   4.442 +        * GLX_MIPMAP_TEXTURE_EXT is set to TRUE and <config> does not
   4.443 +          have GLX_BIND_TO_MIPMAP_EXT set to TRUE.
   4.444 +
   4.445 +        * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_1D_EXT
   4.446 +          and <config> does not have GLX_TEXTURE_1D_BIT_EXT set.
   4.447 +
   4.448 +        * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_2D_EXT
   4.449 +          and <config> does not have GLX_TEXTURE_2D_BIT_EXT set.
   4.450 +
   4.451 +        * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_RECTANGLE_EXT
   4.452 +          and <config> does not have GLX_TEXTURE_RECTANGLE_BIT_EXT set.
   4.453 +
   4.454 +    A BadValue error is generated if GLX_TEXTURE_FORMAT_EXT is not
   4.455 +    GLX_TEXTURE_FORMAT_NONE_EXT and the width or height of <pixmap> are
   4.456 +    incompatible with the specified value of GLX_TEXTURE_TARGET_EXT on this
   4.457 +    implementation. (e.g., the pixmap size is not a power of 2 and
   4.458 +    GL_ARB_texture_rectangle is not supported).
   4.459 +
   4.460 +    Modify paragraph 1 of the description of glXDestroyPixmap:
   4.461 +
   4.462 +    ...The storage for the GLX pixmap will be freed when it is not current
   4.463 +    to any client and all color buffers that are bound to a texture object
   4.464 +    have been released.
   4.465 +
   4.466 +
   4.467 +    Modifications to seciton 3.3.6, "Querying Attributes"
   4.468 +
   4.469 +    Modify paragraph 1 of the description of glXQueryDrawable:
   4.470 +
   4.471 +    ...<attribute> must be set to one of GLX_WIDTH, GLX_HEIGHT,
   4.472 +    GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID,
   4.473 +    GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT or GLX_MIPMAP_TEXTURE_EXT
   4.474 +    or a BadValue error is generated.
   4.475 +
   4.476 +    Modify paragraph 3 of the description of glXQueryDrawable:
   4.477 +
   4.478 +    ...If <draw> is a GLXWindow or GLXPixmap and <attribute> is set to
   4.479 +    GLX_PRESERVED_CONTENTS or GLX_LARGEST_PBUFFER, or if <draw> is a
   4.480 +    GLXWindow or GLXPbuffer and <attribute> is set to GLX_TEXTURE_FORMAT_EXT,
   4.481 +    GLX_TEXTURE_TARGET_EXT, or GLX_MIPMAP_TEXTURE_EXT, the contents of <value>
   4.482 +    are undefined.
   4.483 +
   4.484 +    Add a new section 3.3.6.1, "Texturing From Drawables"
   4.485 +
   4.486 +    The command
   4.487 +
   4.488 +        void glXBindTexImageEXT (Display *dpy,
   4.489 +                                 GLXDrawable draw,
   4.490 +                                 int buffer,
   4.491 +                                 int *attrib_list);
   4.492 +
   4.493 +    defines a one- or two-dimensional texture image.  The texture image is taken
   4.494 +    from <buffer> and need not be copied.  The texture target, the texture
   4.495 +    format, and the size of the texture components are derived from attributes
   4.496 +    of <draw>.
   4.497 +
   4.498 +    The drawable attribute GLX_TEXTURE_FORMAT_EXT determines the base internal
   4.499 +    format of the texture.  The component sizes are also determined by drawable
   4.500 +    attributes as shown in table 3.4a.
   4.501 +
   4.502 +    Add new table 3.4a: Size of texture components:
   4.503 +
   4.504 +    Texture component Size
   4.505 +    ----------------- --------------
   4.506 +    R                 GLX_RED_SIZE
   4.507 +    G                 GLX_GREEN_SIZE
   4.508 +    B                 GLX_BLUE_SIZE
   4.509 +    A                 GLX_ALPHA_SIZE
   4.510 +
   4.511 +    The texture target is derived from the GLX_TEXTURE_TARGET_EXT attribute of
   4.512 +    <draw>.  If the texture target for the drawable is GLX_TEXTURE_2D_EXT or
   4.513 +    GLX_TEXTURE_RECTANGLE_EXT, then buffer defines a 2D texture for the current
   4.514 +    2D or rectangle texture object respectively; if the texture target is
   4.515 +    GLX_TEXTURE_1D_EXT, then buffer defines a 1D texture for the current 1D
   4.516 +    texture object.
   4.517 +
   4.518 +    If <buffer> is not one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT,
   4.519 +    GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, or GLX_AUX0_EXT through
   4.520 +    GLX_AUXn_EXT, where n is one less than the number of AUX buffers supported
   4.521 +    by the FBConfig used to create <draw>, or if the requested buffer is
   4.522 +    missing, a BadValue error is generated.
   4.523 +
   4.524 +    <attrib_list> specifies a list of attributes for the texture.  The list has
   4.525 +    the same structure as described for glXChooseFBConfig.  If <attrib_list> is
   4.526 +    NULL or empty (first attribute of None), then all attributes assume their
   4.527 +    default values.  <attrib_list> must be NULL or empty.
   4.528 +
   4.529 +    If <dpy> and <draw> are the display and drawable for the calling thread's
   4.530 +    current context, glXBindTexImageEXT performs an implicit glFlush.
   4.531 +
   4.532 +    The contents of the texture after the drawable has been bound are defined
   4.533 +    as the result of all rendering that has completed before the call to
   4.534 +    glXBindTexImageEXT.  In other words, the results of any operation which
   4.535 +    has caused damage on the drawable prior to the glXBindTexImageEXT call
   4.536 +    will be represented in the texture.
   4.537 +
   4.538 +    Rendering to the drawable while it is bound to a texture will leave the
   4.539 +    contents of the texture in an undefined state.  However, no
   4.540 +    synchronization between rendering and texturing is done by GLX.  It is
   4.541 +    the application's responsibility to implement any synchronization
   4.542 +    required.
   4.543 +
   4.544 +    If a texture object is deleted before glXReleaseTexImageEXT is called,
   4.545 +    the color buffer is released.
   4.546 +
   4.547 +    It is not an error to call TexImage2D, TexImage1D, CopyTexImage1D, or
   4.548 +    CopyTexImage2D to replace an image of a texture object that has a color
   4.549 +    buffer bound to it.  However, these calls will cause the color buffer to be
   4.550 +    released and new memory to be allocated for the texture.  Note that the
   4.551 +    color buffer is released even if the image that is being defined is a mipmap
   4.552 +    level that was not defined by the color buffer.  GenerateMipmapEXT is an
   4.553 +    exception.  GenerateMipmapEXT can be used to define mipmap levels for
   4.554 +    drawables that have been created with GLX_MIPMAP_TEXTURE_EXT set.  Calling
   4.555 +    GenerateMipmapEXT on a drawable that was created without
   4.556 +    GLX_MIPMAP_TEXTURE_EXT is undefined.
   4.557 +
   4.558 +    The results of calling glXBindTexImageEXT when GENERATE_MIPMAP_SGIS is TRUE
   4.559 +    are undefined.
   4.560 +
   4.561 +    If glXBindTexImageEXT is called and the drawable attribute
   4.562 +    GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch
   4.563 +    error is generated.
   4.564 +
   4.565 +    Currently, only pixmaps can be bound to textures.  If <draw> is not a
   4.566 +    valid GLXPixmap, then a GLXBadPixmap error is generated.
   4.567 +
   4.568 +    glXBindTexImageEXT is ignored if there is no current GLX rendering context.
   4.569 +
   4.570 +    To release a color buffer that is being used as a texture, call
   4.571 +
   4.572 +       void glXReleaseTexImageEXT (Dislpay *dpy, GLXDrawable draw, int buffer);
   4.573 +
   4.574 +    <buffer> must be one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT,
   4.575 +    GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, and GLX_AUX0_EXT through
   4.576 +    GLX_AUXn_EXT, where n is one less than the number of AUX buffers
   4.577 +    supported by the FBConfig used to create <draw> or a BadValue error
   4.578 +    is generated.
   4.579 +
   4.580 +    The contents of the color buffer are unaffected by glXReleaseTexImageEXT.
   4.581 +
   4.582 +    If the specified color buffer is no longer bound to a texture (e.g.,
   4.583 +    because the texture object was deleted), then glXReleaseTexImageEXT has no effect;
   4.584 +    no error is generated.
   4.585 +
   4.586 +    When a color buffer is released (e.g., by calling glXReleaseTexImageEXT or
   4.587 +    implicitly by calling a routine such as TexImage2D), all textures that were
   4.588 +    defined by the color buffer become NULL.
   4.589 +
   4.590 +    If glXReleaseTexImageEXT is called and the drawable attribute
   4.591 +    GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch
   4.592 +    error is generated.
   4.593 +
   4.594 +    Currently, only pixmaps can be bound to textures.  If <draw> is not a
   4.595 +    valid GLXPixmap, then a GLXBadPixmap error is generated.
   4.596 +
   4.597 +
   4.598 +Usage Examples
   4.599 +
   4.600 +    Example 1: Bind redirected window to texture:
   4.601 +
   4.602 +    XGetWindowAttributes (display, window, &attrib);
   4.603 +
   4.604 +    visualid = XVisualIDFromVisual (attrib.visual);
   4.605 +
   4.606 +    fbconfigs = glXGetFBConfigs (display, screen, &nfbconfigs);
   4.607 +    for (i = 0; i < nfbconfigs; i++)
   4.608 +    {
   4.609 +        visinfo = glXGetVisualFromFBConfig (display, fbconfigs[i]);
   4.610 +        if (!visinfo || visinfo->visualid != visualid)
   4.611 +            continue;
   4.612 +
   4.613 +        glXGetFBConfigAttrib (display, fbconfigs[i], GLX_DRAWABLE_TYPE, &value);
   4.614 +        if (!(value & GLX_PIXMAP_BIT))
   4.615 +            continue;
   4.616 +
   4.617 +        glXGetFBConfigAttrib (display, fbconfigs[i],
   4.618 +                              GLX_BIND_TO_TEXTURE_TARGETS_EXT,
   4.619 +                              &value);
   4.620 +        if (!(value & GLX_TEXTURE_2D_BIT_EXT))
   4.621 +            continue;
   4.622 +
   4.623 +        glXGetFBConfigAttrib (display, fbconfigs[i],
   4.624 +                              GLX_BIND_TO_TEXTURE_RGBA_EXT,
   4.625 +                              &value);
   4.626 +        if (value == FALSE)
   4.627 +        {
   4.628 +            glXGetFBConfigAttrib (display, fbconfigs[i],
   4.629 +                                  GLX_BIND_TO_TEXTURE_RGB_EXT,
   4.630 +                                  &value);
   4.631 +            if (value == FALSE)
   4.632 +                continue;
   4.633 +        }
   4.634 +
   4.635 +        glXGetFBConfigAttrib (display, fbconfigs[i],
   4.636 +                              GLX_Y_INVERTED_EXT,
   4.637 +                              &value);
   4.638 +        if (value == TRUE)
   4.639 +        {
   4.640 +            top = 0.0f;
   4.641 +            bottom = 1.0f;
   4.642 +        }
   4.643 +        else
   4.644 +        {
   4.645 +            top = 1.0f;
   4.646 +            bottom = 0.0f;
   4.647 +        }
   4.648 +
   4.649 +        break;
   4.650 +    }
   4.651 +
   4.652 +    if (i == nfbconfigs)
   4.653 +        /* error 1 */
   4.654 +
   4.655 +    pixmap = XCompositeNameWindowPixmap (display, window);
   4.656 +    pixmapAttribs = { GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT,
   4.657 +                      GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_FORMAT_RGBA_EXT,
   4.658 +                      None };
   4.659 +    glxpixmap = glXCreatePixmap (display, fbconfigs[i], pixmap, pixmapAttribs);
   4.660 +
   4.661 +    glGenTextures (1, &texture);
   4.662 +    glBindTexture (GL_TEXTURE_2D, texture);
   4.663 +
   4.664 +    glXBindTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT, NULL);
   4.665 +
   4.666 +    glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
   4.667 +    glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
   4.668 +
   4.669 +    /* draw using pixmap as texture */
   4.670 +    glBegin (GL_QUADS);
   4.671 +
   4.672 +    glTexCoord2d (0.0f, bottom);
   4.673 +    glVertex2d (0.0f, 0.0f);
   4.674 +
   4.675 +    glTexCoord2d (0.0f, top);
   4.676 +    glVertex2d (0.0f, 1.0f);
   4.677 +
   4.678 +    glTexCoord2d (1.0f, top);
   4.679 +    glVertex2d (1.0f, 1.0f);
   4.680 +
   4.681 +    glTexCoord2d (1.0f, bottom);
   4.682 +    glVertex2d (1.0f, 0.0f);
   4.683 +
   4.684 +    glEnd ();
   4.685 +
   4.686 +    glXReleaseTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT);
   4.687 +
   4.688 +
   4.689 +Version History
   4.690 +    
   4.691 +    1. 26 Nov 2005 - DavidR
   4.692 +        Initial version
   4.693 +    2. 01 Dec 2005 - JamesJ
   4.694 +        -Adapted spec language from draft version of GLX_ARB_render_texture.
   4.695 +        -Added glXDrawableAttribute to set attributes.
   4.696 +        -Modified glXBindTexImageEXT to take an attrib_list parameter.
   4.697 +        -Added support for cubemap and 1D texture targets.
   4.698 +        -Added attribute to set the texture target when creating the
   4.699 +         drawable.
   4.700 +        -Updated the issues section.
   4.701 +        -Added mipmap support.  Support is not required.
   4.702 +        -Specified results of texturing from a drawable when it has been
   4.703 +         rendered to while bound to a texture as undefined until
   4.704 +         glXReleaseTexImageEXT has been called.  Allows implementations
   4.705 +         that need to perform an implicit copy after rendering occurs
   4.706 +         to be compatible with this specification.
   4.707 +    3. 04 Dec 2005 - DavidR
   4.708 +        -Changed name to GLX_EXT_texture_from_pixmap.
   4.709 +        -Changed spec regarding what happens when a pixmap that is bound
   4.710 +         to a texture is rendered to. Having textures be undefined once
   4.711 +         they are rendered to makes it useless for a compositing manager,
   4.712 +         which is a major use case for this extension.
   4.713 +        -Added support for not specifying texture target when creating a
   4.714 +         pixmap. Allows implementations to select whatever target it
   4.715 +         finds most suitable.
   4.716 +    4. 05 Dec 2005 - JamesJ
   4.717 +        -Changed the default value of GLX_TEXTURE_TARGET_EXT from
   4.718 +         GLX_NO_TEXTURE_EXT to something usable.  Eliminated
   4.719 +         GLX_NO_TEXTURE_EXT.
   4.720 +        -Eliminated GLX_TEXTURE_NONE_EXT.
   4.721 +        -Removed language referring to sharing of color buffers when
   4.722 +         pixmaps are bound to textures.
   4.723 +        -Updated issues.
   4.724 +
   4.725 +    5. 13 Dec 2005 - JamesJ
   4.726 +        -Removed cube map support and rendering to multiple mipmap
   4.727 +         levels support.
   4.728 +
   4.729 +    6. 20 Jan 2006 - JamesJ
   4.730 +        -Specified textures are y-inverted.
   4.731 +
   4.732 +    7. 23 Jan 2006 - AaronP
   4.733 +        -Fix typos, make some things clearer.  Replace ocurrences of "released
   4.734 +         back to the drawable" with "released".
   4.735 +
   4.736 +    8. 01 Feb 2006 - AndyR
   4.737 +        -Fix minor typos.
   4.738 +
   4.739 +    9. 03 Feb 2006 - JamesJ
   4.740 +        -Added some new issues and their resolutions.
   4.741 +        -Finalized some issues that had been in discussion.
   4.742 +        -Made drawable y-inversion a queryable attribute of the drawable.
   4.743 +        -Moved detailed explanation of y-inverted addressing to the issues
   4.744 +         section
   4.745 +        -Updated example to demonstrate proper use of the y-inverted
   4.746 +         attribute.
   4.747 +
   4.748 +    10. 06 Feb 2006 - DavidR
   4.749 +        -Made GLX_Y_INVERTED_EXT an FBConfig attribute instead of a drawable
   4.750 +         attribute.
   4.751 +        -Removed GLX_TEXTURE_CUBE_MAP_EXT.
   4.752 +        -Fix minor typo.
   4.753 +
   4.754 +    11. 07 Feb 2006 - JamesJ
   4.755 +        -Added description of GLX_Y_INVERTED_EXT GLXFBConfig attribute, based
   4.756 +         on description of the drawable attribute of the same name from
   4.757 +         and earlier version of the specification.
   4.758 +        -Removed language requiring applications to re-bind a pixmap to a
   4.759 +         texture to gurantee contents of the texture are updated after a
   4.760 +         pixmap has been rendered to.
   4.761 +        -Added Aaron Plattner and Andy Ritger to contributors section.
   4.762 +
   4.763 +    12. 14 Feb 2006 - JamesJ
   4.764 +        -Disallowed rendering to a drawable while it is bound as a texture
   4.765 +         and defined the exact contents of a texture after a drawable has
   4.766 +         been bound to it.
   4.767 +
   4.768 +    13. 09 Mar 2006 - JamesJ
   4.769 +        -Add a context tag member to the vendor private requests.  This field
   4.770 +         is part of the vendor private header, and is needed to specify which
   4.771 +         context the BindTexImageEXT and ReleaseTexImageEXT requests correspond
   4.772 +         to.
   4.773 +        -Changed texture target bitfield values to not skip numbers removed in
   4.774 +         earlier updates.
   4.775 +
   4.776 +    14. 13 Mar 2006 - JamesJ
   4.777 +        -Only require GLX_SGIX_fbconfig + GLX 1.2.
   4.778 +        -Clarify language regarding the result of rendering to drawables bound
   4.779 +         to textures.
   4.780 +        -Added GLX_FRONT_EXT and GLX_BACK_EXT tokens.
   4.781 +
   4.782 +    15. 18 Apr 2006 - JamesJ
   4.783 +        -Allocated enum values and opcodes.
   4.784 +        -Require GLX 1.3.  GLX_SGIX_fbconfig doesn't allow creating pixmaps
   4.785 +         with attributes.
   4.786 +        -Added more arguments for not supporting rendering to multiple levels
   4.787 +         of a texture with this extension.
   4.788 +        -Fixed the inconsistencies in the return type of glXBindTexImageEXT
   4.789 +         and glXReleaseTexImageEXT.  It is now listed as void throughout.
   4.790 +
   4.791 +    16. 12 Sep 2006 - JamesJ
   4.792 +        -Fix ordering of GLX protocol
   4.793 +
   4.794 +    17. 10 Feb 2009 - Jon Leech
   4.795 +	-Fix typo reported by Jonathan Knispel.