sync with current spec from the modular tree.XORG-6_8_99_14

1 files changed, 178 insertions, 65 deletions

diff --git a/specs/Render/protocol b/specs/Render/protocol
index 72b3b61..65750ac 100644
--- a/specs/Render/protocol
+++ b/specs/Render/protocol
@@ -1,8 +1,8 @@
 			The X Rendering Extension
-			      Version 0.7
-			        2002-11-6
+			      Version 0.9
+			        2004-7-23
 			      Keith Packard
-			    keithp@xfree86.org
+			    keithp@keithp.com
 
 1. Introduction
 
@@ -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.
@@ -187,6 +187,7 @@ POINTFIX	[
 		]
 POLYEDGE	{ Sharp, Smooth }
 POLYMODE	{ Precise, Imprecise }
+REPEAT          { None, Regular, Pad, Reflect }
 COLORPOINT	[
 			point:		POINTFIX
 			color:		COLOR
@@ -208,9 +209,13 @@ LINEFIX		[
 			p1, p2:		POINTFIX
 		]
 TRAP		[
+			top, bottom:	SPANFIX
+		]
+TRAPEZOID	[
 			top, bottom:	FIXED
 			left, right:	LINEFIX
 		]
+(TRAPEZOID is deprecated)
 COLORTRIANGLE	[
 			p1, p2, p3:	COLORPOINT
 		]
@@ -245,6 +250,10 @@ GLYPHELT32	[
 		]
 GLYPHITEM32	GLYPHELT32 or GLYPHABLE
 
+ANIMCURSORELT	[
+			cursor:		CURSOR
+			delay:		CARD32
+		]
 7. Standard PictFormats
 
 The server must support a Direct PictFormat with 8 bits each of red, green,
@@ -368,22 +377,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:
 
@@ -400,21 +400,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.
 
----
-
-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.
+Rasterization
+Alpha values are generated by point sampling the coverage of a square
+surrounding the center of each pixel by the polygon. 
 
----
+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
@@ -432,16 +431,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
@@ -456,8 +445,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
@@ -465,13 +454,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
@@ -587,8 +592,7 @@ CreatePicture
 	The value-mask and value-list specify attributes of the picture that
 	are to be explicitly initialized.  The possible values are:
 	
-	repeat:			BOOL
-	fill-nearest:		BOOL
+	repeat:			REPEAT
 	alpha-map:		PICTURE or None
 	alpha-x-origin:		INT16
 	alpha-y-origin:		INT16
@@ -606,16 +610,8 @@ CreatePicture
 	values control how pixels outside the geometry of the drawable are
 	computed.
 	
-	Fill-nearest indicates that pixel values outside of the drawable
-	geometry should be replaced the nearest available pixel within the
-	drawable geometry is used.  When multiple pixels are equidistant,
-	those with smaller Y and then X values are preferred.  Otherwise,
-	missing pixels are replaced with transparent.
-
-	Repeat indicates that the drawable contents should be treated
-	as if tiled in both directions.  Pixels falling in missing
-	areas of this tile are replaced according to the fill-nearest
-	rule.
+	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
@@ -812,14 +808,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:
@@ -1095,6 +1092,109 @@ CreateCursor
 	Subsequent drawing in the source has an undefined effect on the
 	cursor.  The server might or might not make a copy of the picture.
 
+CreateAnimCursor
+	cid:		CURSOR
+	cursors:	LISTofANIMCURSORELT
+
+	Errors:		Alloc, IDChoice, Cursor
+
+	This request creates a cursor and associates identifier cid with it.
+	When active, the cursor image on the screen will cycle through
+	'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.
+	
+CreateSolidFill
+	pid: 		PICTURE
+	color:		COLOR	
+
+	Creates a Source picture that represents a solid fill with
+	the specified color. 
+
+CreateLinearGradient
+	pid:		PICTURE
+	p1, p2:		POINTFIX
+	spread:		CARD16
+	nstops:		CARD16
+	stops:		LISTofFIXED
+	stop_colors:	LISTofCOLOR
+
+	Errors:		Alloc, Value
+
+	Creates a source picture representing a linear Gradient. The gradients
+	bounds are defined by the two end points p1 and p2. 
+
+	The gradient has nstops stop points between 0 and 1, each
+	having a stop color defined in stop_colors.
+
+	The array of stops has to contain values between 0 and 1 (inclusive) and
+	has to be ordered in increasing size or a Value error is generated. If 
+	p1 == p2 a Value error is generated.
+
+	The colors are non premultiplied.
+
+CreateRadialGradient
+	pid:		PICTURE
+	inner_center:	POINTFIX
+	outer_center:	POINTFIX
+	inner_radius:	FIXED
+	outer_radius:	FIXED
+	spread:		CARD16
+	nstops:		CARD16
+	stops:		LISTofFIXED
+	stop_colors:	LISTofCOLOR
+
+	Errors:		Alloc, Value
+
+	Creates a source picture representing a linear Gradient. The
+	gradients bounds are defined by a center point, a focal point and a
+	radius around the center.
+
+	The gradient has nstops stop points between 0 and 1, each
+	having a stop color defined in stop_colors.
+
+	The array of stops has to contain values between 0 and 1 (inclusive) and
+	has to be ordered in increasing size or a Value error is generated. The inner
+	circle has to be completely contained inside the outer one or a Value error is 
+	generated. 
+
+	The colors are non premultiplied.
+
+CreateConicalGradient
+	pid:		PICTURE
+	center:		POINTFIX
+	angle:		FIXED
+	spread:		CARD16
+	nstops:		CARD16
+	stops:		LISTofFIXED
+	stop_colors:	LISTofCOLOR
+
+	Errors:		Alloc, Value
+
+	Creates a source picture representing a conical Gradient. The
+	gradient is defined by a center point and an angle (in degrees).
+
+	The gradient has nstops stop points between 0 and 1, each
+	having a stop color defined in stop_colors.
+
+	The array of stops has to contain values between 0 and 1 (inclusive) and
+	has to be ordered in increasing size or a Value error is generated.
+
+	The colors are non premultiplied.
+
+	
 15. Extension Versioning
 
 The Render extension was developed in parallel with the implementation to
@@ -1141,3 +1241,16 @@ what each version before 1.0 implemented:
 
 	0.7:
 		QueryPictIndexValues
+	0.8:
+		CreateAnimCursor
+	0.9:
+		AddTrapezoids
+
+	0.10:	
+		CreateSolidFill
+		CreateLinearGradient
+		CreateRadialGradient
+		CreateConicalGradient
+
+		The repeat picture attribute now supports Pad and
+		Reflect, older versions only supported None and Normal.