Update spec to match current implementation.

1 files changed, 145 insertions, 14 deletions

diff --git a/renderproto.txt b/renderproto.txt
index bba445f..908b4f9 100644
--- a/renderproto.txt
+++ b/renderproto.txt
@@ -28,6 +28,12 @@ This extension was the work of many people, in particular:
  +	Jon Leech, Brad Grantham and Allen Akin for patiently explaining
 	how OpenGL works.
 
+ +	Carl Worth for providing the sample implementation of
+ 	trapezoid rendering
+
+ +	Sam Pottle and Jamey Sharp for helping demonstrate the correctness
+ 	of the trapezoid specification.
+
 3. Rendering Model
 
 Render provides a single rendering operation which can be used in a variety of
@@ -154,7 +160,7 @@ DITHERINFO	[
 			height:		CARD16
 		]
 
-FIXED		32-bit value (top 24 are integer portion, bottom 8 are fraction)
+FIXED		32-bit value (top 16 are integer portion, bottom 16 are fraction)
 POINTFIX	[
 			x, y: FIXED
 		]
@@ -177,8 +183,12 @@ QUAD		[
 TRIANGLE	[
 			p1, p2, p3:	POINTFIX
 		]
+LINEFIX		[
+			p1, p2:		POINTFIX
+		]
 TRAP		[
-			top, bottom:	SPANFIX
+			top, bottom:	FIXED
+			left, right:	LINEFIX
 		]
 COLORTRIANGLE	[
 			p1, p2, p3:	COLORPOINT
@@ -264,6 +274,24 @@ come from the following table:
 
 ---
 
+Here are the disjoint and conjoint operators which need to be
+factored into the table above
+
+		Disjoint			Conjoint
+		Fa		Fb		Fa		Fb
+(0,0,0,0)	0		0		0		0
+(0,A,0,A)	1		0		1		0
+(0,0,B,B)	0		1		0		1
+(0,A,B,A)	1		min((1-a)/b,1)	1		max(1-a/b,0)
+(0,A,B,B)	min((1-b)/a,1)	1		max(1-b/a,0)	1		
+(0,0,0,A)	max(1-(1-b)/a,0) 0		min(1,b/a)	0
+(0,0,0,B)	0		max(1-(1-a)/b,0) 0		min(a/b,1)
+(0,A,0,0)	min(1,(1-b)/a)	0		max(1-b/a,0)	0
+(0,0,B,0)	0		min(1,(1-a)/b)	0		max(1-a/b,0)
+(0,0,B,A)	max(1-(1-b)/a,0) min(1,(1-a)/b)	 min(1,b/a)	max(1-a/b,0)
+(0,A,0,B)	min(1,(1-b)/a)	max(1-(1-a)/b,0) max(1-b/a,0)	min(1,a/b)
+(0,A,B,0)	min(1,(1-b)/a)	min(1,(1-a)/b)	max(1-b/a,0)	max(1-a/b,0)
+
 Saturate matches GL with FUNC_ADD, SRC_ALPHA_SATURATE, ONE, except
 that it uses premultiplied alphas while GL uses non-premultiplied alphas.
 
@@ -307,16 +335,25 @@ in the general compositing operator along with a supplied source image:
 	tmp = Rasterize (polygon)
 	Composite (op, dst, src, tmp)
 
-When rasterized with Sharp edges, the mask is generated by setting pixels
-inside the polygon to 1 and pixels outside the mask to 0.
+When rasterized with Sharp edges, the mask is computed with a depth of 1 so
+that all of the mask values are either 0 or 1.
 
 When rasterized with Smooth edges, the mask is generated by creating a square
 around each pixel coordinate and computing the amount of that square covered
-by the polygon.  Yes, this ignores sampling theory but it provides a precise
+by the polygon.  This ignores sampling theory but it provides a precise
 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.
+
+---
+
 When rasterized in Precise mode, the pixelization will match this
 specification exactly.
 
@@ -686,12 +723,30 @@ Trapezoids
 	src:		PICTURE
 	src-x, src-y:   INT16
 	dst:		PICTURE
+	mask-format:	PICTFORMAT or None
 	traps:		LISTofTRAP
 
-	This request rasterizes the list of trapezoids.  For each span, the
-	left coordinate must be less than or equal to the right coordinate.
-	The y coordinate of the top span must be less than or equal to the 
-	y coordinate of the bottom span.  Results are undefined otherwise.
+	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:
+
+		tmp = temporary alpha picture (in mask-format)
+		Combine (Zero, tmp, tmp, None)
+		for each trapezoid
+			Combine (Add, tmp, trapezoid, None)
+		Combine (op, dst, source, tmp)
+
+	When mask-format is None, trapezoids are rendered in the order
+	specified directly to the destination:
+
+		for each trapezoid
+			Combine (op, dst, source, trapezoid)
 
 Triangles
 
@@ -699,17 +754,34 @@ Triangles
 	src:		PICTURE
 	src-x, src-y:   INT16
 	dst:		PICTURE
-	traps:		LISTofTRIANGLE
+	mask-format:	PICTFORMAT or None
+	triangles:	LISTofTRIANGLE
 
 	This request rasterizes the list of triangles in the order they
 	occur in the list.
 
+	When mask-format is not None, triangles are rendered in the
+	following way with the effective mask computed in mask-format:
+
+		tmp = temporary alpha picture (in mask-format)
+		Combine (Zero, tmp, tmp, None)
+		for each trapezoid
+			Combine (Add, tmp, trapezoid, None)
+		Combine (op, dst, source, tmp)
+
+	When mask-format is None, triangles are rendered in the order
+	specified directly to the destination:
+
+		for each trapezoid
+			Combine (op, dst, source, trapezoid)
+
 TriStrip
 
 	op:		PICTOP
 	src:		PICTURE
 	src-x, src-y:   INT16
 	dst:		PICTURE
+	mask-format:	PICTFORMAT or None
 	points:		LISTofPOINTFIX
 
 	Triangles are formed by initially using the first three points and
@@ -717,11 +789,27 @@ TriStrip
 	the list. If fewer than three points are provided, this request does
 	nothing.
 
+	When mask-format is not None, triangles are rendered in the
+	following way with the effective mask computed in mask-format:
+
+		tmp = temporary alpha picture (in mask-format)
+		Combine (Zero, tmp, tmp, None)
+		for each trapezoid
+			Combine (Add, tmp, trapezoid, None)
+		Combine (op, dst, source, tmp)
+
+	When mask-format is None, triangles are rendered in the order
+	specified directly to the destination:
+
+		for each trapezoid
+			Combine (op, dst, source, trapezoid)
+
 TriFan
 	op:		PICTOP
 	src:		PICTURE
 	src-x, src-y:   INT16
 	dst:		PICTURE
+	mask-format:	PICTFORMAT or None
 	points:		LISTofPOINTFIX
 
 	Triangles are formed by initially using the first three points and
@@ -729,17 +817,26 @@ TriFan
 	int the list. If fewer than three points are provided, this request
 	does nothing.
 
-???
+	When mask-format is not None, triangles are rendered in the
+	following way with the effective mask computed in mask-format:
 
-Should I bother with these two compressed triangle representations?
+		tmp = temporary alpha picture (in mask-format)
+		Combine (Zero, tmp, tmp, None)
+		for each trapezoid
+			Combine (Add, tmp, trapezoid, None)
+		Combine (op, dst, source, tmp)
 
-???
+	When mask-format is None, triangles are rendered in the order
+	specified directly to the destination:
+
+		for each trapezoid
+			Combine (op, dst, source, trapezoid)
 
 ColorTrapezoids
 
 	op:		PICTOP
 	dst:		PICTURE
-	triangles:	LISTofCOLORTRAP
+	trapezoids:	LISTofCOLORTRAP
 
 	The geometry of the trapezoids must meet the same requirements as
 	for the Trapezoids request.  The trapezoids are filled in the order
@@ -962,3 +1059,37 @@ CompositeGlyphs32
 		for each glyph
 			Combine (op, dst, source, glyph)
 
+14. Extension Versioning
+
+The Render extension was developed in parallel with the implementation to
+ensure the feasibility of various portions of the design.  As portions of
+the extension are implemented, the version number of the extension has
+changed to reflect the portions of the standard provied.  This document
+describes the intent for version 1.0 of the specification, the partial
+implementations have version numbers less than that.  Here's a list of
+what each version before 1.0 implemented:
+
+	0.0:	
+		No disjoint/conjoint operators
+		No component alpha
+		Composite
+		CreateGlyphSet
+		FreeGlyphSet
+		AddGlyphs
+		CompositeGlyphs
+
+	0.1:
+		Component alpha
+		FillRectangles
+
+	0.2:
+		Disjoint/Conjoint operators
+
+	0.3:
+		FreeGlyphs
+
+	0.4:
+		Trapezoids
+		Triangles
+		TriStrip
+		TriFan