Add docs. Change {nNorm,nGrab} to CARD32. {Begin,End} -> {Clear,Activate}

The use of CompositeSetMesh{Begin,End} is also different to {Clear,Activate}

3 files changed, 53 insertions, 36 deletions

diff --git a/composite.h b/composite.h
index 8023e76..40d5625 100644
--- a/composite.h
+++ b/composite.h
@@ -54,8 +54,8 @@
 #define CompositeRedirectAutomatic		0
 #define CompositeRedirectManual			1
 
-#define CompositeSetMeshBegin			(1<<0)
-#define CompositeSetMeshEnd			(1<<1)
+#define CompositeSetMeshClear			(1<<0)
+#define CompositeSetMeshActivate		(1<<1)
 
 #define X_CompositeQueryVersion			0
 #define X_CompositeRedirectWindow		1
diff --git a/compositeproto.h b/compositeproto.h
index 3c99039..8acc868 100644
--- a/compositeproto.h
+++ b/compositeproto.h
@@ -193,9 +193,9 @@ typedef struct {
     Window  window B32;
     CARD8   flags;
     CARD8   pad1;
-    CARD16  nNorm B16;
-    CARD16  nGrab B16;
     CARD16  pad2  B16;
+    CARD32  nNorm B32;
+    CARD32  nGrab B32;
 } xCompositeSetTriangularCoordinateMeshReq;
 
 #define sz_xCompositeSetTriangularCoordinateMeshReq sizeof(xCompositeSetTriangularCoordinateMeshReq)
diff --git a/compositeproto.txt b/compositeproto.txt
index 4b86621..6aa3312 100644
--- a/compositeproto.txt
+++ b/compositeproto.txt
@@ -150,6 +150,7 @@ The composite extension does not define any new errors.
 5. Types
 
 	UPDATETYPE	{ Automatic, Manual }
+	MESHTYPE	{ Clear, Activate }
 
 	CompositeCoordinate
 		child:			Window
@@ -300,40 +301,56 @@ operations other than QueryVersion.
 
 12. External coordinate transformation (0.4 and later)
 
-    RedirectCoordinate
+    SetTriangularCoordinateMesh
 
 		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'.
+		flags:				MESHTYPE
+		nNorm:				CARD32
+		nGrab:				CARD32
+
+		errors: Window, Access, Length, Value
+
+	This request is the header for the request. Expected to follow is 2n
+	xTriangles, and a 'BadLength' error will be generated otherwise.
+	The first triangle in each pair is a set of coordinates in the parent
+	of 'window', while the second triangle is the corresponding
+	coordinates in the child window. The triangles will be stored in a
+	buffer, until a request with the 'activate' flag is sent. This will
+	free the current mesh (if it exists), and set the current mesh to the
+	mesh in the buffer. Sending the 'clear' flag will clear the buffer
+	before adding the triangles. The 'activate' flag will also clear the
+	buffer. When the 'clear' flag is sent, a buffer capable of holding
+	'nNorm' + 'nGrab' triangles will be allocated, and attempting to
+	upload more than this result in a 'BadValue' error. Sending a request
+	with 'activate' and the total triangles in the buffer not equal to
+	'nNorm' + 'nGrab' will also result in a 'BadValue' error.
+
+	The mesh is used to generate transformed coordinates for redirected
+	windows for input events. The last 'nGrab' triangles will act as if
+	they are not part of the window, even if they generate coordinates
+	within the window. This is useful if during grabs you want certain
+	regions of the screen to give coordinates inside the window, although
+	the window isn't actually there (eg. cutting a hole in a window)
 	
-    TransformCoordinate
+	'BadAccess' will be generated if a client attempts to set a mesh for
+	a window which is not Manual update, or for which it is not the 
+	Manual update client. 'BadWindow' will be generated if the window is
+	not redirected.
+
+    RedirectWindowInput
 
 		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.
+		destination:			Window
+
+		errors: Window, Access
+
+	This request redirects input from one window to another. Any input
+	generated on 'window' will be sent to 'destination' instead. This is
+	intented to be used to redirect input from input-only windows to
+	redirected window, to allow multiple copies of a window to appear in
+	different stacking positions.
+
+	'BadWindow' will be generated if a client attempts to redirect
+	'window' to one of its descendants, or other situations which would
+	result in an unworkable redirection. 'BadAccess' will be generated if
+	this client isn't allowed to access either window.