[PATCH] Clarify semantics of clipping

[Søren Sandmann Pedersen]

Source clips are applied on top of the transformed and repeated
window, because that way you can clip out an interesting shape of for
example a repeated gradient, and because this makes the implementation
simple and efficient.

GraphicsExposures are never generated.

The hierarchy clip is ignored for source and mask pictures. This is
because GraphicsExposures are not generated anyway, and because
implementing it correctly in the presense of filters and
transformations would be either inefficient or complex.

Also make it explicit that the dither argument is not used.
---
 renderproto.txt |   73 +++++++++++++++++++++++++-----------------------------
 1 files changed, 34 insertions(+), 39 deletions(-)

diff --git a/renderproto.txt b/renderproto.txt
index ef371b9..438ce16 100644
--- a/renderproto.txt
+++ b/renderproto.txt
@@ -607,70 +607,63 @@ CreatePicture
 	dither:			ATOM or None
 	component-alpha:	BOOL
 	
-	When used as a source or mask operand, the repeat and fill-constant
-	values control how pixels outside the geometry of the drawable are
-	computed.
-	
-	Repeat indicates how the drawable contents should be extented
-	in both directions.  
+	When used as a source or mask operand, Repeat indicates how the
+	drawable contents should be extented in both directions.
 	
 	The alpha channel of alpha-map is used in place of any alpha channel
 	contained within the drawable for all rendering operations.  The
 	alpha-mask origin is interpreted relative to the origin of drawable.
-	Rendering is additionally clipped by the geometry of alpha-map.
-	Exposures to the window do not affect the contents of alpha-map.
-	Alpha-map must refer to a picture containing a Pixmap, not a Window
-	(or a Match error results).
+	Rendering is additionally clipped by the geometry and clip mask of
+	alpha-map.  Exposures to the window do not affect the contents of
+	alpha-map.  Alpha-map must refer to a picture containing a Pixmap,
+	not a Window (or a Match error results).
 
 	The clip-mask restricts reads and writes to drawable.  Only pixels
 	where the clip-mask has bits set to 1 are read or written.  Pixels
 	are not accessed outside the area covered by the clip-mask or where
 	the clip-mask has bits set to 0.  The clip-mask affects all graphics
 	requests, including sources.  The clip-mask origin is interpreted
-	relative to the origin of drawable.  If a pixmap is specified as the
-	clip-mask, it must have depth 1 and have the same root as the
+	relative to the origin of the picture.  If a pixmap is specified as
+	the clip-mask, it must have depth 1 and have the same root as the
 	drawable (or a Match error results).  If clip-mask is None, then
 	pixels are always drawn, regardless of the clip origin.  The
 	clip-mask can also be set with the SetPictureClipRectangles request.
-	
-	For ClipByChildren, both source and destination windows are
-	additionally clipped by all viewable InputOutput children.  For
-	IncludeInferiors , neither source nor destination window is clipped
-	by inferiors.  This will result in including subwindow contents in
-	the source and drawing through subwindow boundaries of the
-	destination.  The use of IncludeInferiors with a source or
+	Transformations, filters and repeat modes do not affect the clip
+	mask.
+
+	For ClipByChildren, destination - but not source - windows are
+	additionally clipped by all viewable InputOutput children.
+
+	For IncludeInferiors, neither source nor destination windows are
+	clipped by inferiors.  This will result in including subwindow
+	contents in the source and drawing through subwindow boundaries of
+	the destination.  The use of IncludeInferiors with a source or
 	destination window of one depth with mapped inferiors of differing
 	depth is not illegal, but the semantics are undefined by this
 	extension.
 
-	The graphics-exposures flag controls GraphicsExposure event
-	generation for Composite requests (and any similar requests
-	defined by additional extensions).
+	The graphics-exposures flag is ignored. GraphicsExposure events are
+	never generated by this extension.
 
-	Poly-edge and poly-mode control the rasterization of polygons
-	as described above.
+	Poly-edge and poly-mode control the rasterization of polygons as
+	described above.
 
-	Dither selects which of the available dither patterns should
-	be used.  If dither is None, no dithering will be done.
+	Dither is ignored.
 
-	Component-alpha indicates whether each image component is
-	intended as a separate alpha value when the picture is used
-	as a mask operand.
+	Component-alpha indicates whether each image component is intended as
+	a separate alpha value when the picture is used as a mask operand.
 
 	The default component values are
 
 		Component		Default
 		-------------------------------
-		repeat			False
-		fill-nearest:		False
+		repeat			None
 		clip-x-origin        	0
 		clip-y-origin          	0
 		clip-mask		None
-		graphics-exposures	True
 		subwindow-mode		ClipByChildren
 		poly-edge		Smooth
 		poly-mode		Precise
-		dither			None
 		component-alpha		False
 
 ChangePicture
@@ -699,12 +692,14 @@ SetPictureClipRectangles
 	This request changes clip-mask in picture to the specified list of
 	rectangles and sets the clip origin.  Input and output will be
 	clipped to remain contained within the rectangles.  The clip origin
-	is interpreted relative to the origin of the drawable associated
-	with picture.  The rectangle coordinates are interpreted relative to
-	the clip origin.  Note that the list of rectangles can be empty,
-	which effectively disables output.  This is the opposite of passing
-	None as the clip-mask in CreatePicture and ChangePicture.
-	
+	is interpreted relative to the origin of picture after
+	transformations and repeats have been applied. The rectangle
+	coordinates are interpreted relative to the clip origin.
+
+	The list of rectangles can be empty, which effectively disables
+	output.  This is the opposite of passing None as the clip-mask in
+	CreatePicture and ChangePicture.
+
 	Note that output is clipped to the union of all of the rectangles
 	and that no particular ordering among the rectangles is required.
 
-- 
1.6.2.2