--- ../0.83/protocol 2004-05-18 22:46:13.000000000 -0700 +++ protocol 2007-03-27 11:16:43.003372000 -0700 @@ -1,6 +1,6 @@ The X Rendering Extension - Version 0.8 - 2003-5-3 + Version 0.10 + 2005-07-01 Keith Packard keithp@keithp.com @@ -8,7 +8,7 @@ The X Rendering Extension (Render) introduces digital image composition as the foundation of a new rendering model within the X Window System. -Rendering geometric figures is accomplished by client-side tesselation into +Rendering geometric figures is accomplished by client-side tessellation into either triangles or trapezoids. Text is drawn by loading glyphs into the server and rendering sets of them. @@ -29,7 +29,7 @@ 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 @@ ] POLYEDGE { Sharp, Smooth } POLYMODE { Precise, Imprecise } +REPEAT { None, Regular, Pad, Reflect } COLORPOINT [ point: POINTFIX color: COLOR @@ -208,9 +209,13 @@ p1, p2: POINTFIX ] TRAP [ + top, bottom: SPANFIX + ] +TRAPEZOID [ top, bottom: FIXED left, right: LINEFIX ] +(TRAPEZOID is deprecated) COLORTRIANGLE [ p1, p2, p3: COLORPOINT ] @@ -366,28 +371,19 @@ To construct the source and mask operands, the computed pixels values are transformed through a homogeneous matrix, filtered and then used in the -fundemental rendering operator described above. Each screen provides a list +fundamental rendering operator described above. Each screen provides a list of supported filter names. There are a few required filters, and several 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. +Render provides only two kinds of polygons, trapezoids and triangles. To +improve efficiency, several different wire encodings exist for each. -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. - -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,28 +400,27 @@ 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 same coordinates in each polygon then the sum of alpha values for pixels inside the union of the two polygons must be precisely one. - + Translationally invarient. The pixelization of the polygon must + + Translationally invariant. The pixelization of the polygon must be the same when either the polygon or the target drawable are translated by any whole number of pixels in any direction. @@ -436,16 +431,6 @@ + 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 +445,8 @@ 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 +454,29 @@ 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 @@ -591,8 +592,7 @@ 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 @@ -610,16 +610,8 @@ 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 @@ -816,14 +808,15 @@ 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: @@ -1046,7 +1039,7 @@ The dst-x and dst-y coordinates are relative to the drawable's origin and specify the baseline starting position (the initial glyph origin). Each glyph item is processed in turn. A glyphset item - causes the glyhpset to be used for subsequent glyphs. Switching + causes the glyphset to be used for subsequent glyphs. Switching among glyphsets does not affect the next glyph origin. A glyph element delta-x and delta-y specify additional changes in the position along the x and y axes before the string is drawn; the @@ -1110,12 +1103,101 @@ '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 + nstops: CARD32 + 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 + nstops: CARD32 + stops: LISTofFIXED + stop_colors: LISTofCOLOR + + Errors: Alloc, Value + + Creates a source picture representing a radial 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 + nstops: CARD32 + 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 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 +changed to reflect the portions of the standard provided. 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: @@ -1158,3 +1240,14 @@ 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.