home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / render-protocol.TXT < prev    next >
Text File  |  2001-06-27  |  29KB  |  965 lines
  1.             The X Rendering Extension
  2.                   Version 0.0.15
  3.                     2000-11-19
  4.                   Keith Packard
  5.                 keithp@xfree86.org
  6.  
  7. 1. Introduction
  8.  
  9. The X Rendering Extension (Render) introduces digital image composition as
  10. the foundation of a new rendering model within the X Window System.
  11. Rendering geometric figures is accomplished by client-side tesselation into
  12. either triangles or trapezoids.  Text is drawn by loading glyphs into the
  13. server and rendering sets of them.
  14.  
  15. 2. Acknowledgments
  16.  
  17. This extension was the work of many people, in particular:
  18.  
  19.  +    Thomas Porter and Tom Duff for their formal description
  20.     of image compositing.
  21.  
  22.  +    Rob Pike and Russ Cox who designed the Plan 9 window system from
  23.     which the compositing model was lifted.
  24.  
  25.  +    Juliusz Chroboczek and Raph Levien whose proposal for client-side
  26.     glyph management eliminated font handling from the X server.
  27.  
  28.  +    Jon Leech, Brad Grantham and Allen Akin for patiently explaining
  29.     how OpenGL works.
  30.  
  31. 3. Rendering Model
  32.  
  33. Render provides a single rendering operation which can be used in a variety of
  34. ways to generate images:
  35.  
  36.     dest = (source IN mask) OP dest
  37.  
  38. Where 'IN' is the Porter/Duff operator of that name and 'OP' is any of the
  39. list of compositing operators described below, among which can be found all
  40. of the Porter/Duff binary operators.
  41.  
  42. To use this operator several additional values are required:
  43.  
  44.  +    The destination rectangle.  This is a subset of the destination
  45.      within which the rendering is performed.
  46.  
  47.  +    The source location. This identifies the coordinate in the
  48.      source aligned with the upper left corner of the
  49.     destination rectangle.
  50.  
  51.  +    The mask location. This identifies the coordinate in the
  52.      mask aligned with the upper left corner of the
  53.     destination rectangle.
  54.  
  55.  +    A clip list.  This limits the rendering to the intersection of the
  56.      destination rectangle with this clip list.
  57.  
  58.  +    The OP to use
  59.  
  60.  +    Whether the source should be repeated to cover the destination
  61.        rectangle or whether rendering should be clipped by the source
  62.  
  63.  +    Whether the mask should be repeated to cover the destination
  64.      rectangle or whether rendering should be clipped by the mask
  65.  
  66.  +    Whether the mask has a single alpha value for all four channels or
  67.      whether each mask channel should affect the associated source/dest
  68.     channels.
  69.     
  70. These parameters are variously attached to the operands or included in each
  71. rendering request.
  72.  
  73. 4. Data types
  74.  
  75. The core protocol rendering system uses a pixel model and applies color only
  76. in the final generation of the video signal.  A compositing model operates
  77. on colors, not pixel values so a new datatype is needed to interpret data as
  78. color instead of just bits.
  79.  
  80. The "PictFormat" object holds information needed to translate pixel values
  81. into red, green, blue and alpha channels.  The server has a list of picture
  82. formats corresponding to the various visuals on the screen.  There are two
  83. classes of formats, Indexed and Direct.  Indexed PictFormats hold a list of
  84. pixel values and RGBA values while Direct PictFormats hold bit masks for each
  85. of R, G, B and A.
  86.  
  87. The "Picture" object contains a Drawable, a PictFormat and some
  88. rendering state.  More than one Picture can refer to the same Drawable.
  89.  
  90. 5. Errors
  91.  
  92. Errors are sent using core X error reports.
  93.  
  94. PictFormat
  95.     A value for a PICTFORMAT argument does not name a defined PICTFORMAT.
  96.  
  97. Picture
  98.     A value for a PICTURE argument does not name a defined PICTURE.
  99.  
  100. PictOp
  101.     A value for a PICTOP argument does not name a defined PICTOP.
  102.  
  103. GlyphSet
  104.     A value for a GLYPHSET argument does not name a defined GLYPHSET.
  105.  
  106. Glyph
  107.     A value for a GLYPH argument does not name a defined GLYPH in the
  108.     glyphset.
  109.  
  110. 6. Protocol Types
  111.  
  112. PICTURE        32-bit value (top three bits guaranteed to be zero)
  113. PICTFORMAT    32-bit value (top three bits guaranteed to be zero)
  114. PICTTYPE    { Indexed, Direct }
  115. PICTOP        { Clear, Src, Dst, Over, OverReverse, In, InReverse,
  116.           Out, OutReverse, Atop, AtopReverse, Xor, Add, Saturate }
  117. COLOR        [    
  118.             red, green, blue, alpha: CARD16
  119.         ]
  120. CHANNELMASK    [
  121.             shift, mask: CARD16
  122.         ]
  123. DIRECTFORMAT    [
  124.             red, green, blue, alpha: CHANNELMASK 
  125.         ]
  126. INDEXVALUE    [ 
  127.             pixel: Pixel; 
  128.             red, green, blue, alpha: CARD16 
  129.         ]
  130. PICTFORMINFO    [
  131.             id:        PICTFORMAT
  132.             type:        PICTTYPE
  133.             depth:        CARD8
  134.             direct:        DIRECTFORMAT
  135.             colormap:    COLORMAP or None
  136.         ]
  137.  
  138. PICTVISUAL    [
  139.             visual:        VISUALID or None
  140.             format:        PICTFORMAT
  141.         ]
  142.  
  143. PICTDEPTH    [
  144.             depth:        CARD8
  145.             visuals:    LISTofPICTVISUAL
  146.         ]
  147.  
  148. PICTSCREEN    LISTofPICTDEPTH
  149.  
  150. DITHERINFO    [
  151.             name:        ATOM
  152.             format:        PICTFORMAT
  153.             width:        CARD16
  154.             height:        CARD16
  155.         ]
  156.  
  157. FIXED        32-bit value (top 24 are integer portion, bottom 8 are fraction)
  158. POINTFIX    [
  159.             x, y: FIXED
  160.         ]
  161. POLYEDGE    { Sharp, Smooth }
  162. POLYMODE    { Precise, Imprecise }
  163. COLORPOINT    [
  164.             point:        POINTFIX
  165.             color:        COLOR
  166.         ]
  167. SPANFIX        [
  168.             left, right, y: FIXED
  169.         ]
  170. COLORSPANFIX    [
  171.             left, right, y: FIXED
  172.             left_color:    COLOR
  173.             right_color:    COLOR
  174. QUAD        [
  175.             p1, p2, p3, p4:    POINTFIX
  176.         ]
  177. TRIANGLE    [
  178.             p1, p2, p3:    POINTFIX
  179.         ]
  180. TRAP        [
  181.             top, bottom:    SPANFIX
  182.         ]
  183. COLORTRIANGLE    [
  184.             p1, p2, p3:    COLORPOINT
  185.         ]
  186. COLORTRAP    [
  187.             top, bottom:    COLORSPANFIX
  188.         ]
  189. GLYPHSET    32-bit value (top three bits guaranteed to be zero)
  190. GLYPH        32-bit value
  191. GLYPHINFO    [
  192.             width, height:    CARD16
  193.             x, y:        INT16
  194.             off-x, off-y:    INT16
  195.         ]
  196. PICTGLYPH    [
  197.             info:        GLYPHINFO
  198.             x, y:        INT16
  199.         ]
  200. GLYPHABLE    GLYPHSET or FONTABLE
  201. GLYPHELT8    [
  202.             dx, dy:        INT16
  203.             glyphs:        LISTofCARD8
  204.         ]
  205. GLYPHITEM8    GLYPHELT8 or GLYPHABLE
  206. GLYPHELT16    [
  207.             dx, dy:        INT16
  208.             glyphs:        LISTofCARD16
  209.         ]
  210. GLYPHITEM16    GLYPHELT16 or GLYPHABLE
  211. GLYPHELT32    [
  212.             dx, dy:        INT16
  213.             glyphs:        LISTofCARD32
  214.         ]
  215. GLYPHITEM32    GLYPHELT32 or GLYPHABLE
  216.  
  217. 7. Standard PictFormats
  218.  
  219. The server must support a Direct PictFormat with 8 bits each of red, green,
  220. blue and alpha as well as a Direct PictFormat with 8 bits of red, green and
  221. blue and 0 bits of alpha.  The server must also support Direct PictFormats
  222. with 1, 4 and 8 bits of alpha and 0 bits of r, g and b.
  223.  
  224. Pixel component values lie in the close range [0,1].  These values are
  225. encoded in a varying number of bits.  Values are encoded in a straight
  226. forward manner.  For a component encoded in m bits, a binary encoding b
  227. is equal to a component value of b/(2^m-1).
  228.  
  229. A Direct PictFormat with zero bits of alpha component is declared to have
  230. alpha == 1 everywhere.  A Direct PictFormat with zero bits of red, green and
  231. blue is declared to have red, green, blue == 0 everywhere.  If any of red,
  232. green or blue components are of zero size, all are of zero size.  Direct
  233. PictFormats never have colormaps and are therefore screen independent.
  234.  
  235. Indexed PictFormats never have alpha channels and the direct component is all
  236. zeros.  Indexed PictFormats always have a colormap in which the specified
  237. colors are allocated read-only and are therefore screen dependent.
  238.  
  239. 8. Compositing Operators
  240.  
  241. For each pixel, the four channels of the image are computed with:
  242.  
  243.     C = Ca * Fa + Cb * Fb
  244.  
  245. where C, Ca, Cb are the values of the respective channels and Fa and Fb
  246. come from the following table:
  247.  
  248.     PictOp        Fa            Fb
  249.     ------------------------------------------
  250.     Clear        0            0
  251.     Src        1            0
  252.     Dst        0            1
  253.     Over        1            1-Aa
  254.     OverReverse    1-Ab            1
  255.     In        Ab            0
  256.     InReverse    0            Aa
  257.     Out        1-Ab            0
  258.     OutReverse    0            1-Aa
  259.     Atop        Ab            1-Aa
  260.     AtopReverse    1-Ab            Aa
  261.     Xor        1-Ab            1-Aa
  262.     Add        1            1
  263.     Saturate    min(1,(1-Ab)/Aa)    1
  264.  
  265. ---
  266.  
  267. Saturate matches GL with FUNC_ADD, SRC_ALPHA_SATURATE, ONE, except
  268. that it uses premultiplied alphas while GL uses non-premultiplied alphas.
  269.  
  270. Remember the idea is to apply (src In mask) Saturate Dst so that
  271. computing (src In mask) effectively applies alpha values of 'mask' to
  272. src; the server could 'short circuit' that computation by only multiplying
  273. the alpha channel and then applying the regular GL SRC_ALPHA_SATURATE
  274. operator.
  275.  
  276. ---
  277.  
  278. The result of any compositing operator is always limited to the range
  279. [0,1] for each component.  Components whose value would be greater than 1
  280. are set to 1.
  281.  
  282. When the mask contains separate alpha values for each channel, the
  283. alpha value resulting from the combination of that value with the source
  284. alpha channel is used in the final image composition.
  285.  
  286. 9. Polygon Rasterization
  287.  
  288. All polygons must be convex.  Rendering of concave polygons is unspecified
  289. except that the result must obey the clipping rules.
  290.  
  291. Each polygon request fills the region closed by the specified path.  The
  292. path is automatically closed if the last point does not coincide with the
  293. first point.
  294.  
  295. A point is infinitely small and the path is an infinitely thin line.  A
  296. pixel is inside if the center point of the pixel is inside and the center
  297. point is not on the boundary.  If the center point is on the boundary, the
  298. pixel is inside if and only if the polygon interior is immediately to its
  299. right (x increasing direction).  Pixels with centers along a horizontal edge
  300. are a special case and are inside if and only if the polygon interior is
  301. immediately below (y increasing direction).  A polygon contains a pixel if
  302. the pixel is inside the polygon.
  303.  
  304. Polygons are rasterized by implicit generating an alpha mask and using that
  305. in the general compositing operator along with a supplied source image:
  306.  
  307.     tmp = Rasterize (polygon)
  308.     Composite (op, dst, src, tmp)
  309.  
  310. When rasterized with Sharp edges, the mask is generated by setting pixels
  311. inside the polygon to 1 and pixels outside the mask to 0.
  312.  
  313. When rasterized with Smooth edges, the mask is generated by creating a square
  314. around each pixel coordinate and computing the amount of that square covered
  315. by the polygon.  Yes, this ignores sampling theory but it provides a precise
  316. definition which is close to the right answer.  This value is truncated to
  317. the alpha width in the fallback format before application of the compositing
  318. operator.
  319.  
  320. When rasterized in Precise mode, the pixelization will match this
  321. specification exactly.
  322.  
  323. When rasterized in Imprecise mode, the pixelization may deviate from this
  324. specification by up to 1/2 pixel along any edge subject to the following
  325. constraints:
  326.  
  327.  +    Abutting edges must match precisely.  When specifying two polygons
  328.     abutting along a common edge, if that edge is specified with the
  329.     same coordinates in each polygon then the sum of alpha values for
  330.     pixels inside the union of the two polygons must be precisely one.
  331.  
  332.  +    Translationally invarient.  The pixelization of the polygon must
  333.     be the same when either the polygon or the target drawable
  334.     are translated by any whole number of pixels in any direction.
  335.  
  336.  +    Sharp edges are honored.  When the polygon is rasterized with Sharp
  337.     edges, the implicit alpha mask will contain only 1 or 0 for
  338.     each pixel.
  339.  
  340.  +    Order independent. Two identical polygons specified with vertices
  341.     in different orders must generate identical results.
  342.  
  343. Polygons can also be specified with colors for each vertex.  These color
  344. values are interpolated along the edges and across each scanline.
  345.  
  346. When rasterized in Precise mode, the interpolated colors are exact.
  347.  
  348. When rasterized in Imprecise mode, the color of each pixel may optionally be
  349. interpolated from a triangle containing the pixel which is formed from any
  350. three polygon vertices.  Any interpolated color value can err up to 1 lsb in
  351. each channel.
  352.  
  353. 10. Glyph Rendering
  354.  
  355. Glyphs are small alpha masks which can be stored in the X server and
  356. rendered by referring to them by name.  A set of glyphs can be rendered in a
  357. single request.  Glyphs are positioned by subtracting the x, y elements of
  358. the GLYPHINFO from the requested rendering position.  The next glyph
  359. rendering position is set to the current rendering position plus the off-x
  360. and off-y elements.
  361.  
  362. Glyphs are stored in GlyphSets and are named within the GlyphSet with
  363. client-specified 32-bit numbers.
  364.  
  365. Glyphs can be stored in any PictFormat supported by the server.  All glyphs
  366. in a GlyphSet are stored in the same format.
  367.  
  368. 11. Dithering
  369.  
  370. Each screen supports a list of dithers.  There are several standard dithers
  371. with defined pixelization, the server is free to offer others as well.  The
  372. width and height of the dither are a hint about the size of the matrix used
  373. if the dither is ordered.  An unordered dither will have zero in these
  374. fields.
  375.  
  376. The standard dithers are:
  377.  
  378.     "Standard2x2"
  379.     "Standard4x4"
  380.     "Standard128x128"
  381.  
  382. ---
  383.  
  384. Need a notation for specifying pixelization of dithers.
  385.  
  386. ---
  387.  
  388. 12. Extension Initialization
  389.  
  390. The client must negotiate the version of the extension before executing
  391. extension requests.  Behavior of the server is undefined otherwise.
  392.  
  393. QueryVersion
  394.  
  395.     client-major-version:        CARD32
  396.     client-minor-version:        CARD32
  397.  
  398.     ->
  399.  
  400.     major-version:            CARD32
  401.     minor-version:            CARD32
  402.  
  403.     The client sends the highest supported version to the server and
  404.     the server sends the highest version it supports, but no higher than
  405.     the requested version.  Major versions changes can introduce
  406.     incompatibilities in existing functionality, minor version
  407.     changes introduce only backward compatible changes.  It is
  408.     the clients responsibility to ensure that the server supports
  409.     a version which is compatible with its expectations.
  410.  
  411. QueryPictFormats
  412.  
  413.     ->
  414.  
  415.     fallback:    PICTFORMAT
  416.     formats:    LISTofPICTFORMINFO
  417.     screens:    LISTofPICTSCREEN
  418.  
  419.     The server responds with a list of supported PictFormats and
  420.     a list of which PictFormat goes with each visual on each screen.
  421.     Every PictFormat must match a supported depth, but not every
  422.     PictFormat need have a matching visual.
  423.  
  424.     The fallback format is used as an intermediate representation
  425.     in cases where there is no ideal choice.
  426.  
  427. QueryPictIndexValues
  428.  
  429.     format:        PICTFORMAT
  430.  
  431.     ->
  432.  
  433.     values:        LISTofINDEXVALUE
  434.  
  435.     Errors:
  436.         PictFormat, Match
  437.  
  438.     Returns the mapping from pixel values to RGBA values for the
  439.     specified Indexed PictFormat.  If 'format' does not refer to
  440.     an Indexed PictFormat a Match error is generated.
  441.  
  442. QueryDithers
  443.  
  444.     drawable:    DRAWABLE
  445.  
  446.     ->
  447.  
  448.     dithers:    LISTofDITHERINFO
  449.  
  450.     Returns all of the supported dithers on the screen specified by
  451.     drawable.
  452.  
  453. 13. Extension Requests
  454.  
  455. CreatePicture
  456.  
  457.     pid:        PICTURE
  458.     drawable:    DRAWABLE
  459.     format:        PICTFORMAT
  460.     value-mask:    BITMASK
  461.     value-list:    LISTofVALUE
  462.  
  463.     Errors:
  464.         Alloc, Drawable, IDChoice, Match, Pixmap, Picture,
  465.         PictFormat, Value
  466.  
  467.     This request creates a Picture object associated with the specified
  468.     drawable and assigns the identifier pid to it.  Pixel data in the
  469.     image are interpreted according to 'format'.  It is a Match error
  470.     to specify a format with a different depth than the drawable.  If
  471.     the drawable is a Window then the Red, Green and Blue masks must
  472.     match those in the visual for the window else a Match error is
  473.     generated.
  474.  
  475.     The value-mask and value-list specify attributes of the picture that
  476.     are to be explicitly initialized.  The possible values are:
  477.     
  478.     repeat:            BOOL
  479.     alpha-map:        PICTURE or None
  480.     alpha-x-origin:        INT16
  481.     alpha-y-origin:        INT16
  482.     clip-x-origin:        INT16
  483.     clip-y-origin:        INT16
  484.     clip-mask:        PIXMAP or None
  485.     graphics-exposures:    BOOL
  486.     subwindow-mode:        { ClipByChildren, IncludeInferiors }
  487.     poly-edge:        POLYEDGE
  488.     poly-mode:        POLYMODE
  489.     dither:            ATOM or None
  490.     component-alpha:    BOOL
  491.     
  492.     The repeat value controls whether the image is replicated
  493.     when used as the source or mask in a rendering operation.  When
  494.     True, the contents are tiled over the destination instead of clipping
  495.     to the geometry of the drawable.
  496.  
  497.     The alpha channel of alpha-map is used in place of any alpha channel
  498.     contained within the drawable for all rendering operations.  The
  499.     alpha-mask origin is interpreted relative to the origin of drawable.
  500.     Rendering is additionally clipped by the geometry of alpha-map.
  501.     Exposures to the window do not affect the contents of alpha-map.
  502.     Alpha-map must refer to a picture containing a Pixmap, not a Window
  503.     (or a Match error results).
  504.  
  505.     The clip-mask restricts reads and writes to drawable.  Only pixels
  506.     where the clip-mask has bits set to 1 are read or written.  Pixels
  507.     are not accessed outside the area covered by the clip-mask or where
  508.     the clip-mask has bits set to 0.  The clip-mask affects all graphics
  509.     requests, including sources.  The clip-mask origin is interpreted
  510.     relative to the origin of drawable.  If a pixmap is specified as the
  511.     clip-mask, it must have depth 1 and have the same root as the
  512.     drawable (or a Match error results).  If clip-mask is None, then
  513.     pixels are always drawn, regardless of the clip origin.  The
  514.     clip-mask can also be set with the SetPictureClipRectangles request.
  515.     
  516.     For ClipByChildren, both source and destination windows are
  517.     additionally clipped by all viewable InputOutput children.  For
  518.     IncludeInferiors , neither source nor destination window is clipped
  519.     by inferiors.  This will result in including subwindow contents in
  520.     the source and drawing through subwindow boundaries of the
  521.     destination.  The use of IncludeInferiors with a source or
  522.     destination window of one depth with mapped inferiors of differing
  523.     depth is not illegal, but the semantics are undefined by this
  524.     extension.
  525.  
  526.     The graphics-exposures flag controls GraphicsExposure event
  527.     generation for Composite and Transform requests (and any similar
  528.     requests defined by additional extensions).
  529.  
  530.     Poly-edge and poly-mode control the rasterization of polygons
  531.     as described above.
  532.  
  533.     Dither selects which of the available dither patterns should
  534.     be used.  If dither is None, no dithering will be done.
  535.  
  536.     Component-alpha indicates whether each image component is
  537.     intended as a separate alpha value when the picture is used
  538.     as a mask operand.
  539.  
  540.     The default component values are
  541.  
  542.         Component        Default
  543.         -------------------------------
  544.         op            Over
  545.         repeat            False
  546.         clip-x-origin            0
  547.         clip-y-origin              0
  548.         clip-mask        None
  549.         graphics-exposures    True
  550.         subwindow-mode        ClipByChildren
  551.         poly-edge        Smooth
  552.         poly-mode        Precise
  553.         dither            None
  554.         component-alpha        False
  555.  
  556. ChangePicture
  557.  
  558.     pid:        PICTURE
  559.     value-mask:     BITMASK
  560.     value-list:     LISTofVALUE
  561.  
  562.     Errors:
  563.         Picture, Alloc, Pixmap, PictOp, Value
  564.  
  565.     The value-mask and value-list specify which attributes are to be
  566.     changed.  The values and restrictions are the same as for 
  567.     CreatePicture.
  568.  
  569. SetPictureClipRectangles
  570.  
  571.     picture:    PICTURE
  572.     clip-x-origin:    INT16
  573.     clip-y-origin:    INT16
  574.     rectangles:    LISTofRECTANGLE
  575.  
  576.     Errors:
  577.         Alloc, Picture
  578.  
  579.     This request changes clip-mask in picture to the specified list of
  580.     rectangles and sets the clip origin.  Input and output will be
  581.     clipped to remain contained within the rectangles.  The clip origin
  582.     is interpreted relative to the origin of the drawable associated
  583.     with picture.  The rectangle coordinates are interpreted relative to
  584.     the clip origin.  Note that the list of rectangles can be empty,
  585.     which effectively disables output.  This is the opposite of passing
  586.     None as the clip-mask in CreatePicture and ChangePicture.
  587.     
  588.     Note that output is clipped to the union of all of the rectangles
  589.     and that no particular ordering among the rectangles is required.
  590.  
  591. FreePicture
  592.  
  593.     pid:        PICTURE
  594.  
  595.     Errors:
  596.         Picture
  597.  
  598.     This request deletes the association between the resource ID and the
  599.     picture and destroys the picture.
  600.  
  601. Composite
  602.  
  603.     op:        PICTOP
  604.     src:        PICTURE
  605.     mask:        PICTURE or None
  606.     dst:        PICTURE
  607.     src-x, src-y:    INT16
  608.     mask-x, mask-y:    INT16
  609.     dst-x, dst-y:    INT16
  610.     width, height:    CARD16
  611.  
  612.     This request combines the specified rectangle of src and mask with
  613.     the specified rectangle of dst using op as the compositing
  614.     operator.  The coordinates are relative their respective drawable's
  615.     origin.  Rendering is clipped to the geometry of the dst drawable
  616.     and then to the dst clip-list, the src clip-list and the mask
  617.     clip-list.
  618.  
  619.     If the specified rectangle extends beyond src, then if src has
  620.     the repeat attribute set, the src picture will be tiled to
  621.     fill the specified rectangle, otherwise rendering is clipped to
  622.     the src geometry.
  623.  
  624.         If the specified rectangle extends beyond mask, then if mask has
  625.     the repeat attribute set, the mask picture will be tiled to
  626.     fill the specified rectangle, otherwise rendering is clipped to
  627.     the mask geometry.
  628.     
  629.     If src, mask and dst are not in the same format, and one of their
  630.     formats can hold all without loss of precision, they are converted
  631.     to that format.  Alternatively, the server will convert each
  632.     operand to the fallback format.
  633.  
  634.     If mask is None, it is replaced by a constant alpha value of 1.
  635.  
  636.     When dst has clip-notify set, a NoExpose event is sent if the
  637.     rendering operation was not clipped by either src or mask, otherwise
  638.     a sequence of GraphicsExpose events are sent covering areas in dst
  639.     where rendering was clipped by src or mask.
  640.  
  641. Scale
  642.  
  643.     color-scale:    CARD32
  644.     alpha-scale:    CARD32
  645.         src:            PICTURE
  646.         dst:            PICTURE
  647.         src-x, src-y:   INT16
  648.         dst-x, dst-y:   INT16
  649.         width, height:  CARD16
  650.  
  651.     This request replaces the specified rectangle in dst with
  652.     the specified rectangle of src with the components multiplied
  653.     in the following fashion:
  654.  
  655.         dst-red   = src-red   * color-scale / 65536
  656.         dst-green = src-green * color-scale / 65536
  657.         dst-blue  = src-blue  * color-scale / 65536
  658.         dst-alpha = src-alpha * alpha-scale / 65536
  659.  
  660.     The coordinates are relative their respective drawable's
  661.         origin.  Rendering is clipped to the geometry of the dst drawable
  662.         and then to the dst clip-list, the src clip-list and the mask
  663.         clip-list.
  664.  
  665.         If the specified rectangle extends beyond src, then if src has
  666.         the repeat attribute set, the src picture will be tiled to
  667.         fill the specified rectangle, otherwise rendering is clipped to
  668.         the src geometry.
  669.  
  670. FillRectangles
  671.  
  672.     op:        PICTOP
  673.     dst:        PICTURE
  674.     color:        COLOR
  675.     rects:        LISTofRECTANGLE
  676.  
  677.     This request combines color with the destination drawable in the
  678.     area specified by rects.  Each rectangle is combined separately;
  679.     overlapping areas will be rendered multiple times.  The effect is
  680.     equivalent to compositing with a repeating source picture filled with
  681.     the specified color.
  682.  
  683. Trapezoids
  684.  
  685.     op:        PICTOP
  686.     src:        PICTURE
  687.     src-x, src-y:   INT16
  688.     dst:        PICTURE
  689.     traps:        LISTofTRAP
  690.  
  691.     This request rasterizes the list of trapezoids.  For each span, the
  692.     left coordinate must be less than or equal to the right coordinate.
  693.     The y coordinate of the top span must be less than or equal to the 
  694.     y coordinate of the bottom span.  Results are undefined otherwise.
  695.  
  696. Triangles
  697.  
  698.     op:        PICTOP
  699.     src:        PICTURE
  700.     src-x, src-y:   INT16
  701.     dst:        PICTURE
  702.     traps:        LISTofTRIANGLE
  703.  
  704.     This request rasterizes the list of triangles in the order they
  705.     occur in the list.
  706.  
  707. TriStrip
  708.  
  709.     op:        PICTOP
  710.     src:        PICTURE
  711.     src-x, src-y:   INT16
  712.     dst:        PICTURE
  713.     points:        LISTofPOINTFIX
  714.  
  715.     Triangles are formed by initially using the first three points and
  716.     then by eliminating the first point and appending the next point in
  717.     the list. If fewer than three points are provided, this request does
  718.     nothing.
  719.  
  720. TriFan
  721.     op:        PICTOP
  722.     src:        PICTURE
  723.     src-x, src-y:   INT16
  724.     dst:        PICTURE
  725.     points:        LISTofPOINTFIX
  726.  
  727.     Triangles are formed by initially using the first three points and
  728.     then by eliminating the second point and appending the next point
  729.     int the list. If fewer than three points are provided, this request
  730.     does nothing.
  731.  
  732. ???
  733.  
  734. Should I bother with these two compressed triangle representations?
  735.  
  736. ???
  737.  
  738. ColorTrapezoids
  739.  
  740.     op:        PICTOP
  741.     dst:        PICTURE
  742.     triangles:    LISTofCOLORTRAP
  743.  
  744.     The geometry of the trapezoids must meet the same requirements as
  745.     for the Trapezoids request.  The trapezoids are filled in the order
  746.     they occur in the list.
  747.  
  748. ColorTriangles
  749.  
  750.     op:        PICTOP
  751.     dst:        PICTURE
  752.     triangles:    LISTofCOLORTRIANGLE
  753.  
  754.     The colored triangles are rasterized in the order they occur in the
  755.     list.
  756.  
  757. ???
  758.  
  759. Should I included compressed triangle representations here?
  760.  
  761. ???
  762.  
  763. Transform
  764.  
  765.     op:        PICTOP
  766.     src:            PICTURE
  767.     dst:            PICTURE
  768.     src-quad:    QUAD
  769.     dst-quad:    QUAD
  770.     filter:        { Nearest, ... }
  771.  
  772.     Errors:
  773.         Picture, Value
  774.  
  775.     This request combines the specified quadrilateral of src with the
  776.     specified quadrilateral of dst using op as the compositing operator.
  777.     The coordinates are relative their respective drawable's origin.
  778.     Rendering is clipped to the geometry of the dst drawable and then to
  779.     the dst clip-list and the src clip-list.
  780.  
  781.     If the specified rectangle extends beyond src, then if src has
  782.     the repeat attribute set, the src picture will be tiled to
  783.     fill the specified rectangle, otherwise rendering is clipped to
  784.     the src geometry.
  785.  
  786.         If the specified rectangle extends beyond mask, then if mask has
  787.     the repeat attribute set, the mask picture will be tiled to
  788.     fill the specified rectangle, otherwise rendering is clipped to
  789.     the mask geometry.
  790.     
  791.     The effect of this request is:
  792.  
  793.         tmp_image = affine-transform (src, src-quad * dst-quad)
  794.         tmp_mask = render (dst-quad)
  795.         Composite (op, dst, tmp_image, tmp_mask)
  796.  
  797.     That is, the entire transformed source image is masked by an
  798.     image of the destination quadrilateral and rendered using the Composite
  799.     operator.
  800.  
  801.     If the specified quadrilateral extends beyond src, then if src has
  802.     the repeat attribute set, the src picture will be tiled to
  803.     fill the specified rectangle, otherwise rendering is clipped to
  804.     the src geometry.
  805.     
  806.     It is a Value error to specify a self intersecting quadrilateral for
  807.     either src-quad or dst-quad.
  808.     
  809.     If src and dst are not in the same format, and one of their formats
  810.     can hold both without loss of precision, they are converted to that
  811.     format.  Alternatively, the server will convert each operand to the
  812.     fallback format.
  813.  
  814.     The compositing operator from the src picture is used to merge the
  815.     images together.
  816.  
  817.     If filter is Nearest, then the nearest (converted) pixel values to
  818.     each destination pixel is used without averaging.
  819.  
  820.     When dst has clip-notify set, a NoExpose event is sent if the
  821.     rendering operation was not clipped by src, otherwise a sequence of
  822.     GraphicsExpose events are sent covering areas in dst where rendering
  823.     was clipped by src.
  824.  
  825. ???
  826.  
  827.     What (small) set of filters should be included
  828.  
  829. ???
  830.  
  831. ---
  832.  
  833.     Need to describe in more detail the semantics here
  834.  
  835.     Looks like the geometric extension needs to be tied to the
  836.     compositing extension (sigh).
  837.  
  838. ---
  839.  
  840.  
  841. CreateGlyphSet
  842.  
  843.     gsid:        GLYPHSET
  844.     format:        PICTFORMAT
  845.  
  846.     Errors:
  847.         Alloc, IDChoice, PictFormat, Match
  848.  
  849.     This request creates a container for glyphs.  The glyphset and
  850.     all contained glyphs are destroyed when gsid and any other names
  851.     for the glyphset are freed.  Format must be a Direct format, when
  852.     it contains RGB values, the glyphs are composited using
  853.     component-alpha True, otherwise they are composited using
  854.     component-alpha False.
  855.  
  856. ReferenceGlyphSet
  857.  
  858.     gsid:        GLYPHSET
  859.     existing:    GLYPHSET
  860.  
  861.     Errors:
  862.         Alloc, IDChoice, GlyphSet
  863.  
  864.     This request creates an additional name for the existing glyphset.
  865.     The glyphset will not be freed until all references to it are
  866.     destroyed.
  867.  
  868. FreeGlyphSet
  869.  
  870.     glyphset:    GLYPHSET
  871.  
  872.     Errors:
  873.         GlyphSet
  874.  
  875.     This request frees the name for the glyphset.  When all names have
  876.     been freed, the glyphset and all contained glyphs are freed.
  877.  
  878. AddGlyphs
  879.     glyphset:    GLYPHSET
  880.     glyphids:    LISTofCARD32
  881.     glyphs:        LISTofGLYPHINFO
  882.     data:        LISTofBYTE
  883.  
  884.     Errors:
  885.         GlyphSet, Alloc
  886.  
  887.     This request adds glyphs to glyphset.  The image for the glyphs
  888.     are stored with each glyph in a separate Z-format image padded to a
  889.     32-bit boundary.  Existing glyphs with the same names are replaced.
  890.  
  891. AddGlyphsFromPicture
  892.  
  893.     glyphset:    GLYPHSET
  894.     src:        PICTURE
  895.     glyphs:        LISTofPICTGLYPH
  896.  
  897.     Errors:
  898.         GlyphSet, Alloc
  899.  
  900.     This request adds glyphs to glyphset by copying them from src from
  901.     the locations included in glyphs.  Existing glyphs with the same
  902.     names are replaced.  Src may be in a different PictFormat than
  903.     glyphset, in which case the images are converted to the glyphset
  904.     format.
  905.     
  906. FreeGlyphs
  907.  
  908.     glyphset:    GLYPHSET
  909.     glyphs:        LISTofGLYPH
  910.  
  911.     Errors:
  912.         GlyphSet, Match
  913.  
  914.     This request removes glyphs from glyphset.  Each glyph must exist
  915.     in glyphset (else a Match error results).
  916.  
  917. CompositeGlyphs8
  918. CompositeGlyphs16
  919. CompositeGlyphs32
  920.  
  921.     op:        PICTOP
  922.     src:        PICTURE
  923.     dst:        PICTURE
  924.     mask-format:    PICTFORMAT or None
  925.     glyphset:    GLYPHABLE
  926.     src-x, src-y:    INT16
  927.     dst-x, dst-y:    INT16
  928.     glyphcmds:    LISTofGLYPHITEM8    CompositeGlyphs8
  929.     glyphcmds:    LISTofGLYPHITEM16    CompositeGlyphs16
  930.     glyphcmds:    LISTofGLYPHITEM32    CompositeGlyphs32
  931.  
  932.     Errors:
  933.         Picture, PictOp, PictFormat, GlyphSet, Glyph
  934.  
  935.     The dst-x and dst-y coordinates are relative to the drawable's
  936.     origin and specify the baseline starting position (the initial glyph
  937.     origin).  Each glyph item is processed in turn.  A glyphset item
  938.     causes the glyhpset to be used for subsequent glyphs.  Switching
  939.     among glyphsets does not affect the next glyph origin.  A glyph
  940.     element delta-x and delta-y specify additional changes in the
  941.     position along the x and y axes before the string is drawn; the
  942.     deltas are always added to the glyph origin.
  943.  
  944.     All contained GLYPHSETs are always transmitted most significant byte
  945.     first.  
  946.     
  947.     If a GlyphSet error is generated for an item, the previous items may
  948.     have been drawn.
  949.     
  950.     When mask-format is not None, glyphs are rendered in the following
  951.     way with the effective mask computed in mask-format:
  952.  
  953.         tmp = temporary alpha picture
  954.         Combine (Zero, tmp, tmp, None)
  955.         for each glyph
  956.             Combine (Add, tmp, glyph, None)
  957.         Combine (op, dst, source, tmp)
  958.  
  959.     When mask-format is None, glyphs are rendered in the order specified
  960.     directly to the destination:
  961.  
  962.         for each glyph
  963.             Combine (op, dst, source, glyph)
  964.  
  965.