2004-07-29 Keith Packard <keithp@keithp.com>

	* configure.ac:
	* protocol:
	* render.h:
	* renderproto.h:
	Specify new AddTraps request.
	Change pixelization specification.

1 files changed, 68 insertions, 52 deletions

diff --git a/renderproto.txt b/renderproto.txt
index e6bae96..3c8e492 100644
--- a/renderproto.txt
+++ b/renderproto.txt
@@ -1,6 +1,6 @@
 			The X Rendering Extension
-			      Version 0.8
-			        2003-5-3
+			      Version 0.9
+			        2004-7-23
 			      Keith Packard
 			    keithp@keithp.com
 
@@ -29,7 +29,7 @@ This extension was the work of many people, in particular:
 	how OpenGL works.
 
  +	Carl Worth for providing the sample implementation of
- 	trapezoid rendering
+ 	trapezoid rendering and showing how broken the spec was
 
  +	Sam Pottle and Jamey Sharp for helping demonstrate the correctness
  	of the trapezoid specification.
@@ -208,9 +208,13 @@ LINEFIX		[
 			p1, p2:		POINTFIX
 		]
 TRAP		[
+			top, bottom:	SPANFIX
+		]
+TRAPEZOID	[
 			top, bottom:	FIXED
 			left, right:	LINEFIX
 		]
+(TRAPEZOID is deprecated)
 COLORTRIANGLE	[
 			p1, p2, p3:	COLORPOINT
 		]
@@ -372,22 +376,13 @@ required filter alias which must map to one of the available filters.
 
 10. Polygon Rasterization
 
-All polygons must be convex.  Rendering of concave polygons is unspecified
-except that the result must obey the clipping rules.
-
-Each polygon request fills the region closed by the specified path.  The
-path is automatically closed if the last point does not coincide with the
-first point.
+Render provides only two kinds of polygons, trapezoids and triangles.  To
+improve efficiency, several different wire encodings exist for each. 
 
-A point is infinitely small and the path is an infinitely thin line.  A
-pixel is inside if the center point of the pixel is inside and the center
-point is not on the boundary.  If the center point is on the boundary, the
-pixel is inside if and only if the polygon interior is immediately to its
-right (x increasing direction).  Pixels with centers along a horizontal edge
-are a special case and are inside if and only if the polygon interior is
-immediately below (y increasing direction).  A polygon contains a pixel if
-the pixel is inside the polygon.
+All trapezoids must be convex.  Rendering of concave trapezoids is unspecified
+except that the result must obey the clipping rules.
 
+Composite
 Polygons are rasterized by implicit generating an alpha mask and using that
 in the general compositing operator along with a supplied source image:
 
@@ -404,21 +399,20 @@ definition which is close to the right answer.  This value is truncated to
 the alpha width in the fallback format before application of the compositing
 operator.
 
----
+Rasterization
+Alpha values are generated by point sampling the coverage of a square
+surrounding the center of each pixel by the polygon. 
 
-This needs rewriting to match current trapezoid specification and
-base other polygons on that.  I suspect imprecise polygons will need
-to have a relaxed specification as well; hardware is unlikely to
-meet the "sum to one" constraint.
+In Precise poly mode, the sample points are located in a regular grid.  When
+alpha depth 'e' is even, the regular grid is 2**(e/2) + 1 samples wide and
+2**(e/2) -1 samples high.  For odd alpha depth 'o', the sample grid is 2**o
+- 1 samples wide and 1 sample high.  Note that odd alpha depth usually
+occurs only at depth 1, so this misshapen sample grid has no ill effects.
+The sample grid is centered within the pixel and then each sample point is
+rounded down to a point on the sub-pixel coordinate grid.
 
----
-
-When rasterized in Precise mode, the pixelization will match this
-specification exactly.
-
-When rasterized in Imprecise mode, the pixelization may deviate from this
-specification by up to 1/2 pixel along any edge subject to the following
-constraints:
+In Imprecise mode, the location of the sample points is not specified, but
+the implementation must conform to the following constraints:
 
  +	Abutting edges must match precisely.  When specifying two polygons
 	abutting along a common edge, if that edge is specified with the
@@ -436,16 +430,6 @@ constraints:
  +	Order independent. Two identical polygons specified with vertices
 	in different orders must generate identical results.
 
-Polygons can also be specified with colors for each vertex.  These color
-values are interpolated along the edges and across each scanline.
-
-When rasterized in Precise mode, the interpolated colors are exact.
-
-When rasterized in Imprecise mode, the color of each pixel may optionally be
-interpolated from a triangle containing the pixel which is formed from any
-three polygon vertices.  Any interpolated color value can err up to 1 lsb in
-each channel.
-
 11. Image Filtering
 
 When computing pixels from source and mask images, a filter may be applied
@@ -460,8 +444,8 @@ provided:
 
 	Filter Name	Description
 
-	Nearest		Nearest neighbor filtering
-	Bilinear	Linear interpolation in two dimensions
+	nearest		Nearest neighbor filtering
+	bilinear	Linear interpolation in two dimensions
 
 Additional names may be provided for any filter as aliases.  A set of
 standard alias names are required to be mapped to a provided filter so that
@@ -469,13 +453,29 @@ applications can use the alias names without checking for availability.
 
 	Alias name	Intended interpretation
 	
-	Fast		High performance, quality similar to Nearest
-	Good		Reasonable performance, quality similar to Bilinear
-	Best		Highest quality available, performance may not
+	fast		High performance, quality similar to Nearest
+	good		Reasonable performance, quality similar to Bilinear
+	best		Highest quality available, performance may not
 			be suitable for interactive use
 
 Aliases must map directly to a non-aliased filter name.
 
+There is also a set of standard filters which are not required but may be
+provided.  If they are provided, using the standard name, they must match
+the definition specified here.
+
+	Filter Name	Description
+	
+	convolution	MxN convolution filter.  The values specified
+			in SetPictureFilter are M, N and then M * N
+			filter parameters.  M and N must be integers
+			represented as fixed point numbers.
+	gaussian	Gaussian blur.  The value specified is a radius
+			in pixels (which can be fractional).  A standard
+			Gaussian 2D convolution filter will be applied.
+	binomial	Binomial blur. An approximation of a Gaussian
+			blur using binomial coefficients
+
 12. Glyph Rendering
 
 Glyphs are small alpha masks which can be stored in the X server and
@@ -816,14 +816,15 @@ Trapezoids
 	src-x, src-y:   INT16
 	dst:		PICTURE
 	mask-format:	PICTFORMAT or None
-	traps:		LISTofTRAP
+	traps:		LISTofTRAPEZOID
 
-	This request rasterizes the list of trapezoids.  For each trap, the
-	area between the left and right edges is filled from the top to the
-	bottom.  src-x and src-y register the pattern to the floor of the
-	top x and y coordinate of the left edge of the first trapezoid, they
-	are adjusted for subsequent trapezoids so that the pattern remains
-	globally aligned within the destination.
+	This request rasterizes the list of trapezoids.
+	
+	For each trap, the area between the left and right edges is filled
+	from the top to the bottom.  src-x and src-y register the pattern to
+	the floor of the top x and y coordinate of the left edge of the
+	first trapezoid, they are adjusted for subsequent trapezoids so that
+	the pattern remains globally aligned within the destination.
 
 	When mask-format is not None, trapezoids are rendered in the
 	following way with the effective mask computed in mask-format:
@@ -1110,6 +1111,19 @@ CreateAnimCursor
 	'cursors', showing each cursor in the element for the number of
 	milliseconds indicated by the 'delay' member of that element.
 
+AddTraps
+	picture:	PICTURE
+	off-x, off-y:	INT16
+	trapezoids:	LISTofTRAP
+
+	Errors:		Match
+
+	Each trap is PictOpAdd'ed to 'picture'.  'off-x', 'off-y'
+	are added to each coordinate.
+
+	'picture' must be an alpha-only picture else a 'Match' error is
+	returned.
+	
 15. Extension Versioning
 
 The Render extension was developed in parallel with the implementation to
@@ -1158,3 +1172,5 @@ what each version before 1.0 implemented:
 		QueryPictIndexValues
 	0.8:
 		CreateAnimCursor
+	0.9:
+		AddTrapezoids