path: root/renderproto.txt blob: af158b500590a37c0ffe0c0a1a147e489dfd4345
1 The X Rendering Extension
2 Version 0.10
3 2005-07-01
4 Keith Packard
5 keithp@keithp.com
6
71. Introduction
8
9The X Rendering Extension (Render) introduces digital image composition as
10the foundation of a new rendering model within the X Window System.
11Rendering geometric figures is accomplished by client-side tessellation into
12either triangles or trapezoids. Text is drawn by loading glyphs into the
13server and rendering sets of them.
14
152. Acknowledgments
16
17This 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 + Carl Worth for providing the sample implementation of
32 trapezoid rendering and showing how broken the spec was
33
34 + Sam Pottle and Jamey Sharp for helping demonstrate the correctness
35 of the trapezoid specification.
36
37 + Owen Taylor for helping specify projective transformations
38
393. Rendering Model
40
41Render provides a single rendering operation which can be used in a variety of
42ways to generate images:
43
44 dest = (source IN mask) OP dest
45
46Where 'IN' is the Porter/Duff operator of that name and 'OP' is any of the
47list of compositing operators described below, among which can be found all
48of the Porter/Duff binary operators.
49
50To use this operator several additional values are required:
51
52 + The destination rectangle. This is a subset of the destination
53 within which the rendering is performed.
54
55 + The source location. This identifies the coordinate in the
56 source aligned with the upper left corner of the
57 destination rectangle.
58
59 + The mask location. This identifies the coordinate in the
60 mask aligned with the upper left corner of the
61 destination rectangle.
62
63 + A clip list. This limits the rendering to the intersection of the
64 destination rectangle with this clip list.
65
66 + The OP to use
67
68 + Whether the source should be repeated to cover the destination
69 rectangle, extended with a constant pixel value or extended by
70 using the nearest available source pixel.
71
72 + Whether the mask should be repeated to cover the destination
73 rectangle, extended with a constant pixel value or extended by
74 using the nearest available mask pixel.
75
76 + Whether the mask has a single alpha value for all four channels or
77 whether each mask channel should affect the associated source/dest
78 channels.
79
80 + Whether the source should be reshaped with a projective
81 transformation, and if so, what filter to apply while
82 resampling the data.
83
84 + Whether the mask should be reshaped with a projective
85 transformation, and if so, what filter to apply while
86 resampling the data.
87
88These parameters are variously attached to the operands or included in each
89rendering request.
90
914. Data types
92
93The core protocol rendering system uses a pixel model and applies color only
94in the final generation of the video signal. A compositing model operates
95on colors, not pixel values so a new datatype is needed to interpret data as
96color instead of just bits.
97
98The "PictFormat" object holds information needed to translate pixel values
99into red, green, blue and alpha channels. The server has a list of picture
100formats corresponding to the various visuals on the screen. There are two
101classes of formats, Indexed and Direct. Indexed PictFormats hold a list of
102pixel values and RGBA values while Direct PictFormats hold bit masks for each
103of R, G, B and A.
104
105The "Picture" object contains a Drawable, a PictFormat and some
106rendering state. More than one Picture can refer to the same Drawable.
107
1085. Errors
109
110Errors are sent using core X error reports.
111
112PictFormat
113 A value for a PICTFORMAT argument does not name a defined PICTFORMAT.
114
115Picture
116 A value for a PICTURE argument does not name a defined PICTURE.
117
118PictOp
119 A value for a PICTOP argument does not name a defined PICTOP.
120
121GlyphSet
122 A value for a GLYPHSET argument does not name a defined GLYPHSET.
123
124Glyph
125 A value for a GLYPH argument does not name a defined GLYPH in the
126 glyphset.
127
1286. Protocol Types
129
130PICTURE 32-bit value (top three bits guaranteed to be zero)
131PICTFORMAT 32-bit value (top three bits guaranteed to be zero)
132PICTTYPE { Indexed, Direct }
133PICTOP { Clear, Src, Dst, Over, OverReverse, In, InReverse,
134 Out, OutReverse, Atop, AtopReverse, Xor, Add, Saturate,
135 DisjointClear, DisjointSrc, DisjointDst, DisjointOver,
136 DisjointOverReverse, DisjointIn, DisjointInReverse,
137 DisjointOut, DisjointOutReverse, DisjointAtop,
138 DisjointAtopReverse, DisjointXor,
139 ConjointClear, ConjointSrc, ConjointDst, ConjointOver,
140 ConjointOverReverse, ConjointIn, ConjointInReverse,
141 ConjointOut, ConjointOutReverse, ConjointAtop,
142 ConjointAtopReverse, ConjointXor }
143SUBPIXEL { Unknown, HorizontalRGB, HorizontalBGR,
144 VerticalRGB, VerticalBGR, None
145 }
146COLOR [
147 red, green, blue, alpha: CARD16
148 ]
149CHANNELMASK [
150 shift, mask: CARD16
151 ]
152DIRECTFORMAT [
153 red, green, blue, alpha: CHANNELMASK
154 ]
155INDEXVALUE [
156 pixel: Pixel;
157 red, green, blue, alpha: CARD16
158 ]
159PICTFORMINFO [
160 id: PICTFORMAT
161 type: PICTTYPE
162 depth: CARD8
163 direct: DIRECTFORMAT
164 colormap: COLORMAP or None
165 ]
166
167PICTVISUAL [
168 visual: VISUALID or None
169 format: PICTFORMAT
170 ]
171
172PICTDEPTH [
173 depth: CARD8
174 visuals: LISTofPICTVISUAL
175 ]
176
177PICTSCREEN LISTofPICTDEPTH
178
179FIXED 32-bit value (top 16 are integer portion, bottom 16 are fraction)
180TRANSFORM [
181 p11, p12, p13: FIXED
182 p21, p22, p23: FIXED
183 p31, p32, p33: FIXED
184 ]
185POINTFIX [
186 x, y: FIXED
187 ]
188POLYEDGE { Sharp, Smooth }
189POLYMODE { Precise, Imprecise }
190REPEAT { None, Regular, Pad, Reflect }
191COLORPOINT [
192 point: POINTFIX
193 color: COLOR
194 ]
195SPANFIX [
196 left, right, y: FIXED
197 ]
198COLORSPANFIX [
199 left, right, y: FIXED
200 left_color: COLOR
201 right_color: COLOR
202QUAD [
203 p1, p2, p3, p4: POINTFIX
204 ]
205TRIANGLE [
206 p1, p2, p3: POINTFIX
207 ]
208LINEFIX [
209 p1, p2: POINTFIX
210 ]
211TRAP [
212 top, bottom: SPANFIX
213 ]
214TRAPEZOID [
215 top, bottom: FIXED
216 left, right: LINEFIX
217 ]
218(TRAPEZOID is deprecated)
219COLORTRIANGLE [
220 p1, p2, p3: COLORPOINT
221 ]
222COLORTRAP [
223 top, bottom: COLORSPANFIX
224 ]
225GLYPHSET 32-bit value (top three bits guaranteed to be zero)
226GLYPH 32-bit value
227GLYPHINFO [
228 width, height: CARD16
229 x, y: INT16
230 off-x, off-y: INT16
231 ]
232PICTGLYPH [
233 info: GLYPHINFO
234 x, y: INT16
235 ]
236GLYPHABLE GLYPHSET or FONTABLE
237GLYPHELT8 [
238 dx, dy: INT16
239 glyphs: LISTofCARD8
240 ]
241GLYPHITEM8 GLYPHELT8 or GLYPHABLE
242GLYPHELT16 [
243 dx, dy: INT16
244 glyphs: LISTofCARD16
245 ]
246GLYPHITEM16 GLYPHELT16 or GLYPHABLE
247GLYPHELT32 [
248 dx, dy: INT16
249 glyphs: LISTofCARD32
250 ]
251GLYPHITEM32 GLYPHELT32 or GLYPHABLE
252
253ANIMCURSORELT [
254 cursor: CURSOR
255 delay: CARD32
256 ]
2577. Standard PictFormats
258
259The server must support a Direct PictFormat with 8 bits each of red, green,
260blue and alpha as well as a Direct PictFormat with 8 bits of red, green and
261blue and 0 bits of alpha. The server must also support Direct PictFormats
262with 1, 4 and 8 bits of alpha and 0 bits of r, g and b.
263
264Pixel component values lie in the close range [0,1]. These values are
265encoded in a varying number of bits. Values are encoded in a straight
266forward manner. For a component encoded in m bits, a binary encoding b
267is equal to a component value of b/(2^m-1).
268
269A Direct PictFormat with zero bits of alpha component is declared to have
270alpha == 1 everywhere. A Direct PictFormat with zero bits of red, green and
271blue is declared to have red, green, blue == 0 everywhere. If any of red,
272green or blue components are of zero size, all are of zero size. Direct
273PictFormats never have colormaps and are therefore screen independent.
274
275Indexed PictFormats never have alpha channels and the direct component is all
276zeros. Indexed PictFormats always have a colormap in which the specified
277colors are allocated read-only and are therefore screen dependent. Drawing
278to in Indexed Picture uses only pixel values listed by QueryPictIndexValues.
279Reading from an Indexed Picture uses red, green and blue values from the
280colormap and alpha values from those listed by QueryPictIndexValues. Pixel
281values not present in QueryPictIndexValues are given alpha values of 1.
282
2838. Compositing Operators
284
285For each pixel, the four channels of the image are computed with:
286
287 C = Ca * Fa + Cb * Fb
288
289where C, Ca, Cb are the values of the respective channels and Fa and Fb
290come from the following table:
291
292 PictOp Fa Fb
293 --------------------------------------------------
294 Clear 0 0
295 Src 1 0
296 Dst 0 1
297 Over 1 1-Aa
298 OverReverse 1-Ab 1
299 In Ab 0
300 InReverse 0 Aa
301 Out 1-Ab 0
302 OutReverse 0 1-Aa
303 Atop Ab 1-Aa
304 AtopReverse 1-Ab Aa
305 Xor 1-Ab 1-Aa
306 Add 1 1
307 Saturate min(1,(1-Ab)/Aa) 1
308 DisjointClear 0 0
309 DisjointSrc 1 0
310 DisjointDst 0 1
311 DisjointOver 1 min(1,(1-Aa)/Ab)
312 DisjointOverReverse min(1,(1-Ab)/Aa) 1
313 DisjointIn max(1-(1-Ab)/Aa,0) 0
314 DisjointInReverse 0 max(1-(1-Aa)/Ab,0)
315 DisjointOut min(1,(1-Ab)/Aa) 0
316 DisjointOutReverse 0 min(1,(1-Aa)/Ab)
317 DisjointAtop max(1-(1-Ab)/Aa,0) min(1,(1-Aa)/Ab)
318 DisjointAtopReverse min(1,(1-Ab)/Aa) max(1-(1-Aa)/Ab,0)
319 DisjointXor min(1,(1-Ab)/Aa) min(1,(1-Aa)/Ab)
320 ConjointClear 0 0
321 ConjointSrc 1 0
322 ConjointDst 0 1
323 ConjointOver 1 max(1-Aa/Ab,0)
324 ConjointOverReverse max(1-Ab/Aa,0) 1
325 ConjointIn min(1,Ab/Aa) 0
326 ConjointInReverse 0 min(Aa/Ab,1)
327 ConjointOut max(1-Ab/Aa,0) 0
328 ConjointOutReverse 0 max(1-Aa/Ab,0)
329 ConjointAtop min(1,Ab/Aa) max(1-Aa/Ab,0)
330 ConjointAtopReverse max(1-Ab/Aa,0) min(1,Aa/Ab)
331 ConjointXor max(1-Ab/Aa,0) max(1-Aa/Ab,0)
332
333Saturate and DisjointOverReverse are the same. They match OpenGL
334compositing with FUNC_ADD, SRC_ALPHA_SATURATE, ONE, except that Render uses
335premultiplied alpha while Open GL uses non-premultiplied alpha.
336
337The result of any compositing operator is always limited to the range
338[0,1] for each component. Components whose value would be greater than 1
339are set to 1.
340
341For operations involving division, when the divisor is zero, define the
342quotient to be positive infinity. The result is always well defined
343because the division is surrounded with a max or min operator which will
344give a finite result.
345
346When the mask contains separate alpha values for each channel, the
347alpha value resulting from the combination of that value with the source
348alpha channel is used in the final image composition.
349
3509. Source and Mask Transformations
351
352When fetching pixels from the source or mask pictures, Render provides three
353options for pixel values which fall outside the drawable (this includes
354pixels within a window geometry obscured by other windows).
355
356 + Transparent. Missing values are replaced with transparent.
357
358 + Nearest. Replace missing pixels with the nearest available
359 pixel. Where multiple pixels are equidistant, select
360 those with smallest Y and then smallest X coordinates
361
362 + Tile. Select the pixel which would appear were the
363 drawable tiled to enclose the missing coordinate. If
364 the tiling doesn't cover the coordinate, use the
365 selected Constant or Nearest mode.
366
367When GraphicsExposures are selected in the destination picture, a region
368containing at least the union of all destination pixel values affected by
369data replaced as above is delivered after each compositing operation. If
370the resulting region is empty, a NoExpose event is delivered instead.
371
372To construct the source and mask operands, the computed pixels values are
373transformed through a homogeneous matrix, filtered and then used in the
374fundamental rendering operator described above. Each screen provides a list
375of supported filter names. There are a few required filters, and several
376required filter alias which must map to one of the available filters.
377
37810. Polygon Rasterization
379
380Render provides only two kinds of polygons, trapezoids and triangles. To
381improve efficiency, several different wire encodings exist for each.
382
383All trapezoids must be convex. Rendering of concave trapezoids is unspecified
384except that the result must obey the clipping rules.
385
386Composite
387Polygons are rasterized by implicit generating an alpha mask and using that
388in the general compositing operator along with a supplied source image:
389
390 tmp = Rasterize (polygon)
391 Composite (op, dst, src, tmp)
392
393When rasterized with Sharp edges, the mask is computed with a depth of 1 so
394that all of the mask values are either 0 or 1.
395
396When rasterized with Smooth edges, the mask is generated by creating a square
397around each pixel coordinate and computing the amount of that square covered
398by the polygon. This ignores sampling theory but it provides a precise
399definition which is close to the right answer. This value is truncated to
400the alpha width in the fallback format before application of the compositing
401operator.
402
403Rasterization
404Alpha values are generated by point sampling the coverage of a square
405surrounding the center of each pixel by the polygon.
406
407In Precise poly mode, the sample points are located in a regular grid. When
408alpha depth 'e' is even, the regular grid is 2**(e/2) + 1 samples wide and
4092**(e/2) -1 samples high. For odd alpha depth 'o', the sample grid is 2**o
410- 1 samples wide and 1 sample high. Note that odd alpha depth usually
411occurs only at depth 1, so this misshapen sample grid has no ill effects.
412The sample grid is centered within the pixel and then each sample point is
413rounded down to a point on the sub-pixel coordinate grid.
414
415In Imprecise mode, the location of the sample points is not specified, but
416the implementation must conform to the following constraints:
417
418 + Abutting edges must match precisely. When specifying two polygons
419 abutting along a common edge, if that edge is specified with the
420 same coordinates in each polygon then the sum of alpha values for
421 pixels inside the union of the two polygons must be precisely one.
422
423 + Translationally invariant. The pixelization of the polygon must
424 be the same when either the polygon or the target drawable
425 are translated by any whole number of pixels in any direction.
426
427 + Sharp edges are honored. When the polygon is rasterized with Sharp
428 edges, the implicit alpha mask will contain only 1 or 0 for
429 each pixel.
430
431 + Order independent. Two identical polygons specified with vertices
432 in different orders must generate identical results.
433
43411. Image Filtering
435
436When computing pixels from source and mask images, a filter may be applied
437to the data. This is usually used with a non-identity transformation
438matrix, but filtering may be applied with an identity transformation.
439
440Each filter is given a unique name encoded as an ISO Latin-1 string.
441Filters may be configured with a list of fixed point values; the number of
442parameters and their interpretation is currently left to conventions passed
443outside of the protocol. A set of standard filters are required to be
444provided:
445
446 Filter Name Description
447
448 nearest Nearest neighbor filtering
449 bilinear Linear interpolation in two dimensions
450
451Additional names may be provided for any filter as aliases. A set of
452standard alias names are required to be mapped to a provided filter so that
453applications can use the alias names without checking for availability.
454
455 Alias name Intended interpretation
456
457 fast High performance, quality similar to Nearest
458 good Reasonable performance, quality similar to Bilinear
459 best Highest quality available, performance may not
460 be suitable for interactive use
461
462Aliases must map directly to a non-aliased filter name.
463
464There is also a set of standard filters which are not required but may be
465provided. If they are provided, using the standard name, they must match
466the definition specified here.
467
468 Filter Name Description
469
470 convolution MxN convolution filter. The values specified
471 in SetPictureFilter are M, N and then M * N
472 filter parameters. M and N must be integers
473 represented as fixed point numbers.
474 gaussian Gaussian blur. The value specified is a radius
475 in pixels (which can be fractional). A standard
476 Gaussian 2D convolution filter will be applied.
477 binomial Binomial blur. An approximation of a Gaussian
478 blur using binomial coefficients
479
48012. Glyph Rendering
481
482Glyphs are small alpha masks which can be stored in the X server and
483rendered by referring to them by name. A set of glyphs can be rendered in a
484single request. Glyphs are positioned by subtracting the x, y elements of
485the GLYPHINFO from the requested rendering position. The next glyph
486rendering position is set to the current rendering position plus the off-x
487and off-y elements.
488
489Glyphs are stored in GlyphSets and are named within the GlyphSet with
490client-specified 32-bit numbers.
491
492Glyphs can be stored in any PictFormat supported by the server. All glyphs
493in a GlyphSet are stored in the same format.
494
49513. Extension Initialization
496
497The client must negotiate the version of the extension before executing
498extension requests. Behavior of the server is undefined otherwise.
499
500QueryVersion
501
502 client-major-version: CARD32
503 client-minor-version: CARD32
504
505 ->
506
507 major-version: CARD32
508 minor-version: CARD32
509
510 The client sends the highest supported version to the server and
511 the server sends the highest version it supports, but no higher than
512 the requested version. Major versions changes can introduce
513 incompatibilities in existing functionality, minor version
514 changes introduce only backward compatible changes. It is
515 the clients responsibility to ensure that the server supports
516 a version which is compatible with its expectations.
517
518QueryPictFormats
519
520 ->
521
522 fallback: PICTFORMAT
523 formats: LISTofPICTFORMINFO
524 screens: LISTofPICTSCREEN
525 subpixels: LISTofSUBPIXEL
526
527 Errors:
528 <none>
529
530 The server responds with a list of supported PictFormats and
531 a list of which PictFormat goes with each visual on each screen.
532 Every PictFormat must match a supported depth, but not every
533 PictFormat need have a matching visual.
534
535 The fallback format is used as an intermediate representation
536 in cases where there is no ideal choice.
537
538 The relationship between the red, green and blue elements making
539 up each pixel indexed by screen is returned in subpixels.
540 This list is not present in servers advertising protocol
541 versions earlier than 0.6. This list may be shorter than
542 the number of screens, in which case the remaining screens
543 are given sub pixel order Unknown.
544
545QueryPictIndexValues
546
547 format: PICTFORMAT
548
549 ->
550
551 values: LISTofINDEXVALUE
552
553 Errors:
554 PictFormat, Match
555
556 Returns the mapping from pixel values to RGBA values for the
557 specified Indexed PictFormat. If 'format' does not refer to
558 an Indexed PictFormat a Match error is generated.
559
560QueryFilters
561
562 drawable: DRAWABLE
563
564 ->
565
566 filters: LISTofSTRING8
567 aliases: LISTofCARD16
568
569
57014. Extension Requests
571
572CreatePicture
573
574 pid: PICTURE
575 drawable: DRAWABLE
576 format: PICTFORMAT
577 value-mask: BITMASK
578 value-list: LISTofVALUE
579
580 Errors:
581 Alloc, Drawable, IDChoice, Match, Pixmap, Picture,
582 PictFormat, Value
583
584 This request creates a Picture object associated with the specified
585 drawable and assigns the identifier pid to it. Pixel data in the
586 image are interpreted according to 'format'. It is a Match error
587 to specify a format with a different depth than the drawable. If
588 the drawable is a Window then the Red, Green and Blue masks must
589 match those in the visual for the window else a Match error is
590 generated.
591
592 The value-mask and value-list specify attributes of the picture that
593 are to be explicitly initialized. The possible values are:
594
595 repeat: REPEAT
596 alpha-map: PICTURE or None
597 alpha-x-origin: INT16
598 alpha-y-origin: INT16
599 clip-x-origin: INT16
600 clip-y-origin: INT16
601 clip-mask: PIXMAP or None
602 graphics-exposures: BOOL
603 subwindow-mode: { ClipByChildren, IncludeInferiors }
604 poly-edge: POLYEDGE
605 poly-mode: POLYMODE
606 dither: ATOM or None
607 component-alpha: BOOL
608
609 When used as a source or mask operand, the repeat and fill-constant
610 values control how pixels outside the geometry of the drawable are
611 computed.
612
613 Repeat indicates how the drawable contents should be extented
614 in both directions.
615
616 The alpha channel of alpha-map is used in place of any alpha channel
617 contained within the drawable for all rendering operations. The
618 alpha-mask origin is interpreted relative to the origin of drawable.
619 Rendering is additionally clipped by the geometry of alpha-map.
620 Exposures to the window do not affect the contents of alpha-map.
621 Alpha-map must refer to a picture containing a Pixmap, not a Window
622 (or a Match error results).
623
624 The clip-mask restricts reads and writes to drawable. Only pixels
625 where the clip-mask has bits set to 1 are read or written. Pixels
626 are not accessed outside the area covered by the clip-mask or where
627 the clip-mask has bits set to 0. The clip-mask affects all graphics
628 requests, including sources. The clip-mask origin is interpreted
629 relative to the origin of drawable. If a pixmap is specified as the
630 clip-mask, it must have depth 1 and have the same root as the
631 drawable (or a Match error results). If clip-mask is None, then
632 pixels are always drawn, regardless of the clip origin. The
633 clip-mask can also be set with the SetPictureClipRectangles request.
634
635 For ClipByChildren, both source and destination windows are
636 additionally clipped by all viewable InputOutput children. For
637 IncludeInferiors , neither source nor destination window is clipped
638 by inferiors. This will result in including subwindow contents in
639 the source and drawing through subwindow boundaries of the
640 destination. The use of IncludeInferiors with a source or
641 destination window of one depth with mapped inferiors of differing
642 depth is not illegal, but the semantics are undefined by this
643 extension.
644
645 The graphics-exposures flag controls GraphicsExposure event
646 generation for Composite requests (and any similar requests
647 defined by additional extensions).
648
649 Poly-edge and poly-mode control the rasterization of polygons
650 as described above.
651
652 Dither selects which of the available dither patterns should
653 be used. If dither is None, no dithering will be done.
654
655 Component-alpha indicates whether each image component is
656 intended as a separate alpha value when the picture is used
657 as a mask operand.
658
659 The default component values are
660
661 Component Default
662 -------------------------------
663 repeat False
664 fill-nearest: False
665 clip-x-origin 0
666 clip-y-origin 0
667 clip-mask None
668 graphics-exposures True
669 subwindow-mode ClipByChildren
670 poly-edge Smooth
671 poly-mode Precise
672 dither None
673 component-alpha False
674
675ChangePicture
676
677 pid: PICTURE
678 value-mask: BITMASK
679 value-list: LISTofVALUE
680
681 Errors:
682 Picture, Alloc, Pixmap, PictOp, Value
683
684 The value-mask and value-list specify which attributes are to be
685 changed. The values and restrictions are the same as for
686 CreatePicture.
687
688SetPictureClipRectangles
689
690 picture: PICTURE
691 clip-x-origin: INT16
692 clip-y-origin: INT16
693 rectangles: LISTofRECTANGLE
694
695 Errors:
696 Alloc, Picture
697
698 This request changes clip-mask in picture to the specified list of
699 rectangles and sets the clip origin. Input and output will be
700 clipped to remain contained within the rectangles. The clip origin
701 is interpreted relative to the origin of the drawable associated
702 with picture. The rectangle coordinates are interpreted relative to
703 the clip origin. Note that the list of rectangles can be empty,
704 which effectively disables output. This is the opposite of passing
705 None as the clip-mask in CreatePicture and ChangePicture.
706
707 Note that output is clipped to the union of all of the rectangles
708 and that no particular ordering among the rectangles is required.
709
710SetPictureTransform
711
712 picture: PICTURE
713 transform: TRANSFORM
714
715 Errors:
716 Alloc, Value, Picture
717
718 This request changes the projective transformation used to
719 map coordinates when 'picture' is used as the source or
720 mask in any compositing operation. The transform
721 maps from destination pixel geometry back to the source pixel
722 geometry.
723
724 The matrix must be invertable, else a Value error is generated.
725
726SetPictureFilter
727
728 picture: PICTURE
729 filter: STRING8
730 values: LISTofFIXED
731
732 Errors:
733 Value, Match, Picture
734
735 This request sets the current filter used when picture is a source
736 or mask operand. Filter must be one of the filters supported
737 for the screen associated with picture, else a Match error
738 is generated. If the filter accepts additional parameters,
739 they can be provided in values, incorrect values generate Value
740 errors, too many values generate Match errors. Too few values
741 cause the filter to assume default values for the missing
742 parameters.
743
744 When created, Pictures are set to the Nearest filter.
745
746FreePicture
747
748 pid: PICTURE
749
750 Errors:
751 Picture
752
753 This request deletes the association between the resource ID and the
754 picture. The picture storage will be freed when no other resource
755 references it.
756
757Composite
758
759 op: PICTOP
760 src: PICTURE
761 mask: PICTURE or None
762 dst: PICTURE
763 src-x, src-y: INT16
764 mask-x, mask-y: INT16
765 dst-x, dst-y: INT16
766 width, height: CARD16
767
768 This request combines the specified rectangle of the transformed
769 src and mask operands with the specified rectangle of dst using op
770 as the compositing operator. The coordinates are relative their
771 respective (transformed) drawable's origin. Rendering is clipped
772 to the geometry of the dst drawable and then to the dst clip-list.
773
774 Pixels outside the geometry of src or mask needed for this
775 computation are substituted as described in the Source and Mask
776 Transformations section above.
777
778 If src, mask and dst are not in the same format, and one of their
779 formats can hold all without loss of precision, they are converted
780 to that format. Alternatively, the server will convert each
781 operand to the fallback format.
782
783 If mask is None, it is replaced by a constant alpha value of 1.
784
785 When dst has graphics-exposures true, a region covering all dst
786 pixels affected by substitutions performed on src or mask pixels
787 outside their respective geometries is computed. If that region is
788 empty, a NoExpose event is sent. Otherwise, a sequence of
789 GraphicsExpose events are sent covering that region.
790
791FillRectangles
792
793 op: PICTOP
794 dst: PICTURE
795 color: COLOR
796 rects: LISTofRECTANGLE
797
798 This request combines color with the destination drawable in the
799 area specified by rects. Each rectangle is combined separately;
800 overlapping areas will be rendered multiple times. The effect is
801 equivalent to compositing with a repeating source picture filled with
802 the specified color.
803
804Trapezoids
805
806 op: PICTOP
807 src: PICTURE
808 src-x, src-y: INT16
809 dst: PICTURE
810 mask-format: PICTFORMAT or None
811 traps: LISTofTRAPEZOID
812
813 This request rasterizes the list of trapezoids.
814
815 For each trap, the area between the left and right edges is filled
816 from the top to the bottom. src-x and src-y register the pattern to
817 the floor of the top x and y coordinate of the left edge of the
818 first trapezoid, they are adjusted for subsequent trapezoids so that
819 the pattern remains globally aligned within the destination.
820
821 When mask-format is not None, trapezoids are rendered in the
822 following way with the effective mask computed in mask-format:
823
824 tmp = temporary alpha picture (in mask-format)
825 Combine (Zero, tmp, tmp, None)
826 for each trapezoid
827 Combine (Add, tmp, trapezoid, None)
828 Combine (op, dst, source, tmp)
829
830 When mask-format is None, trapezoids are rendered in the order
831 specified directly to the destination:
832
833 for each trapezoid
834 Combine (op, dst, source, trapezoid)
835
836Triangles
837
838 op: PICTOP
839 src: PICTURE
840 src-x, src-y: INT16
841 dst: PICTURE
842 mask-format: PICTFORMAT or None
843 triangles: LISTofTRIANGLE
844
845 This request rasterizes the list of triangles in the order they
846 occur in the list.
847
848 When mask-format is not None, triangles are rendered in the
849 following way with the effective mask computed in mask-format:
850
851 tmp = temporary alpha picture (in mask-format)
852 Combine (Zero, tmp, tmp, None)
853 for each triangle
854 Combine (Add, tmp, triangle, None)
855 Combine (op, dst, source, tmp)
856
857 When mask-format is None, triangles are rendered in the order
858 specified directly to the destination:
859
860 for each triangle
861 Combine (op, dst, source, triangle)
862
863TriStrip
864
865 op: PICTOP
866 src: PICTURE
867 src-x, src-y: INT16
868 dst: PICTURE
869 mask-format: PICTFORMAT or None
870 points: LISTofPOINTFIX
871
872 Triangles are formed by initially using the first three points and
873 then by eliminating the first point and appending the next point in
874 the list. If fewer than three points are provided, this request does
875 nothing.
876
877 When mask-format is not None, triangles are rendered in the
878 following way with the effective mask computed in mask-format:
879
880 tmp = temporary alpha picture (in mask-format)
881 Combine (Zero, tmp, tmp, None)
882 for each triangle
883 Combine (Add, tmp, triangle, None)
884 Combine (op, dst, source, tmp)
885
886 When mask-format is None, triangles are rendered in the order
887 specified directly to the destination:
888
889 for each triangle
890 Combine (op, dst, source, triangle)
891
892TriFan
893 op: PICTOP
894 src: PICTURE
895 src-x, src-y: INT16
896 dst: PICTURE
897 mask-format: PICTFORMAT or None
898 points: LISTofPOINTFIX
899
900 Triangles are formed by initially using the first three points and
901 then by eliminating the second point and appending the next point
902 int the list. If fewer than three points are provided, this request
903 does nothing.
904
905 When mask-format is not None, triangles are rendered in the
906 following way with the effective mask computed in mask-format:
907
908 tmp = temporary alpha picture (in mask-format)
909 Combine (Zero, tmp, tmp, None)
910 for each triangle
911 Combine (Add, tmp, triangle, None)
912 Combine (op, dst, source, tmp)
913
914 When mask-format is None, triangles are rendered in the order
915 specified directly to the destination:
916
917 for each triangle
918 Combine (op, dst, source, triangle)
919
920ColorTrapezoids
921
922 op: PICTOP
923 dst: PICTURE
924 trapezoids: LISTofCOLORTRAP
925
926 The geometry of the trapezoids must meet the same requirements as
927 for the Trapezoids request. The trapezoids are filled in the order
928 they occur in the list.
929
930ColorTriangles
931
932 op: PICTOP
933 dst: PICTURE
934 triangles: LISTofCOLORTRIANGLE
935
936 The colored triangles are rasterized in the order they occur in the
937 list.
938
939???
940
941Should I included compressed triangle representations here?
942
943???
944
945CreateGlyphSet
946
947 gsid: GLYPHSET
948 format: PICTFORMAT
949
950 Errors:
951 Alloc, IDChoice, PictFormat, Match
952
953 This request creates a container for glyphs. The glyphset and
954 all contained glyphs are destroyed when gsid and any other names
955 for the glyphset are freed. Format must be a Direct format, when
956 it contains RGB values, the glyphs are composited using
957 component-alpha True, otherwise they are composited using
958 component-alpha False.
959
960ReferenceGlyphSet
961
962 gsid: GLYPHSET
963 existing: GLYPHSET
964
965 Errors:
966 Alloc, IDChoice, GlyphSet
967
968 This request creates an additional name for the existing glyphset.
969 The glyphset will not be freed until all references to it are
970 destroyed.
971
972FreeGlyphSet
973
974 glyphset: GLYPHSET
975
976 Errors:
977 GlyphSet
978
979 This request frees the name for the glyphset. When all names have
980 been freed, the glyphset and all contained glyphs are freed.
981
982AddGlyphs
983 glyphset: GLYPHSET
984 glyphids: LISTofCARD32
985 glyphs: LISTofGLYPHINFO
986 data: LISTofBYTE
987
988 Errors:
989 GlyphSet, Alloc
990
991 This request adds glyphs to glyphset. The image for the glyphs
992 are stored with each glyph in a separate Z-format image padded to a
993 32-bit boundary. Existing glyphs with the same names are replaced.
994
995AddGlyphsFromPicture
996
997 glyphset: GLYPHSET
998 src: PICTURE
999 glyphs: LISTofPICTGLYPH
1000
1001 Errors:
1002 GlyphSet, Alloc
1003
1004 This request adds glyphs to glyphset by copying them from src from
1005 the locations included in glyphs. Existing glyphs with the same
1006 names are replaced. Src may be in a different PictFormat than
1007 glyphset, in which case the images are converted to the glyphset
1008 format.
1009
1010FreeGlyphs
1011
1012 glyphset: GLYPHSET
1013 glyphs: LISTofGLYPH
1014
1015 Errors:
1016 GlyphSet, Match
1017
1018 This request removes glyphs from glyphset. Each glyph must exist
1019 in glyphset (else a Match error results).
1020
1021CompositeGlyphs8
1022CompositeGlyphs16
1023CompositeGlyphs32
1024
1025 op: PICTOP
1026 src: PICTURE
1027 dst: PICTURE
1028 mask-format: PICTFORMAT or None
1029 glyphset: GLYPHABLE
1030 src-x, src-y: INT16
1031 dst-x, dst-y: INT16
1032 glyphcmds: LISTofGLYPHITEM8 CompositeGlyphs8
1033 glyphcmds: LISTofGLYPHITEM16 CompositeGlyphs16
1034 glyphcmds: LISTofGLYPHITEM32 CompositeGlyphs32
1035
1036 Errors:
1037 Picture, PictOp, PictFormat, GlyphSet, Glyph
1038
1039 The dst-x and dst-y coordinates are relative to the drawable's
1040 origin and specify the baseline starting position (the initial glyph
1041 origin). Each glyph item is processed in turn. A glyphset item
1042 causes the glyphset to be used for subsequent glyphs. Switching
1043 among glyphsets does not affect the next glyph origin. A glyph
1044 element delta-x and delta-y specify additional changes in the
1045 position along the x and y axes before the string is drawn; the
1046 deltas are always added to the glyph origin.
1047
1048 All contained GLYPHSETs are always transmitted most significant byte
1049 first.
1050
1051 If a GlyphSet error is generated for an item, the previous items may
1052 have been drawn.
1053
1054 When mask-format is not None, glyphs are rendered in the following
1055 way with the effective mask computed in mask-format:
1056
1057 tmp = temporary alpha picture
1058 Combine (Zero, tmp, tmp, None)
1059 for each glyph
1060 Combine (Add, tmp, glyph, None)
1061 Combine (op, dst, source, tmp)
1062
1063 When mask-format is None, glyphs are rendered in the order specified
1064 directly to the destination:
1065
1066 for each glyph
1067 Combine (op, dst, source, glyph)
1068
1069CreateCursor
1070
1071 cid: CURSOR
1072 source: PICTURE
1073 x, y: CARD16
1074
1075 Errors: Alloc, IDChoice, Match, Picture
1076
1077 This request creates a cursor and associates identifier cid with it.
1078 The x and y coordinates define the hotspot relative to the source's
1079 origin and must be a point within the source (or a Match error
1080 results). The resulting picture will nominally be drawn to the
1081 screen with PictOpOver.
1082
1083 The components of the cursor may be transformed arbitrarily to meet
1084 display limitations. In particular, if the display supports only
1085 two colors cursors without translucency, the cursor will be
1086 transformed so that areas less than .5 alpha will be transparent,
1087 else opaque, and areas darker than 50% gray will be black else white.
1088
1089 The source picture can be freed immediately if no further explicit
1090 references to it are to be made.
1091
1092 Subsequent drawing in the source has an undefined effect on the
1093 cursor. The server might or might not make a copy of the picture.
1094
1095CreateAnimCursor
1096 cid: CURSOR
1097 cursors: LISTofANIMCURSORELT
1098
1099 Errors: Alloc, IDChoice, Cursor
1100
1101 This request creates a cursor and associates identifier cid with it.
1102 When active, the cursor image on the screen will cycle through
1103 'cursors', showing each cursor in the element for the number of
1104 milliseconds indicated by the 'delay' member of that element.
1105
1106AddTraps
1107 picture: PICTURE
1108 off-x, off-y: INT16
1109 trapezoids: LISTofTRAP
1110
1111 Errors: Match
1112
1113 Each trap is PictOpAdd'ed to 'picture'. 'off-x', 'off-y'
1114 are added to each coordinate.
1115
1116 'picture' must be an alpha-only picture else a 'Match' error is
1117 returned.
1118
1119CreateSolidFill
1120 pid: PICTURE
1121 color: COLOR
1122
1123 Creates a Source picture that represents a solid fill with
1124 the specified color.
1125
1126CreateLinearGradient
1127 pid: PICTURE
1128 p1, p2: POINTFIX
1129 nstops: CARD32
1130 stops: LISTofFIXED
1131 stop_colors: LISTofCOLOR
1132
1133 Errors: Alloc, Value
1134
1135 Creates a source picture representing a linear Gradient. The gradients
1136 bounds are defined by the two end points p1 and p2.
1137
1138 The gradient has nstops stop points between 0 and 1, each
1139 having a stop color defined in stop_colors.
1140
1141 The array of stops has to contain values between 0 and 1 (inclusive) and
1142 has to be ordered in increasing size or a Value error is generated. If
1143 p1 == p2 a Value error is generated.
1144
1145 The colors are non premultiplied.
1146
1147CreateRadialGradient
1148 pid: PICTURE
1149 inner_center: POINTFIX
1150 outer_center: POINTFIX
1151 inner_radius: FIXED
1152 outer_radius: FIXED
1153 nstops: CARD32
1154 stops: LISTofFIXED
1155 stop_colors: LISTofCOLOR
1156
1157 Errors: Alloc, Value
1158
1159 Creates a source picture representing a radial Gradient. The
1160 gradients bounds are defined by a center point, a focal point and a
1161 radius around the center.
1162
1163 The gradient has nstops stop points between 0 and 1, each
1164 having a stop color defined in stop_colors.
1165
1166 The array of stops has to contain values between 0 and 1 (inclusive) and
1167 has to be ordered in increasing size or a Value error is generated. The inner
1168 circle has to be completely contained inside the outer one or a Value error is
1169 generated.
1170
1171 The colors are non premultiplied.
1172
1173CreateConicalGradient
1174 pid: PICTURE
1175 center: POINTFIX
1176 angle: FIXED
1177 nstops: CARD32
1178 stops: LISTofFIXED
1179 stop_colors: LISTofCOLOR
1180
1181 Errors: Alloc, Value
1182
1183 Creates a source picture representing a conical Gradient. The
1184 gradient is defined by a center point and an angle (in degrees).
1185
1186 The gradient has nstops stop points between 0 and 1, each
1187 having a stop color defined in stop_colors.
1188
1189 The array of stops has to contain values between 0 and 1 (inclusive) and
1190 has to be ordered in increasing size or a Value error is generated.
1191
1192 The colors are non premultiplied.
1193
1194
119515. Extension Versioning
1196
1197The Render extension was developed in parallel with the implementation to
1198ensure the feasibility of various portions of the design. As portions of
1199the extension are implemented, the version number of the extension has
1200changed to reflect the portions of the standard provided. This document
1201describes the intent for version 1.0 of the specification, the partial
1202implementations have version numbers less than that. Here's a list of
1203what each version before 1.0 implemented:
1204
1205 0.0:
1206 No disjoint/conjoint operators
1207 No component alpha
1208 Composite
1209 CreateGlyphSet
1210 FreeGlyphSet
1211 AddGlyphs
1212 CompositeGlyphs
1213
1214 0.1:
1215 Component alpha
1216 FillRectangles
1217
1218 0.2:
1219 Disjoint/Conjoint operators
1220
1221 0.3:
1222 FreeGlyphs
1223
1224 0.4:
1225 Trapezoids
1226 Triangles
1227 TriStrip
1228 TriFan
1229
1230 0.5:
1231 CreateCursor
1232
1233 0.6:
1234 SetPictureTransform
1235 QueryFilters
1236 SetPictureFilter
1237 subpixels member of QueryPictFormats
1238
1239 0.7:
1240 QueryPictIndexValues
1241 0.8:
1242 CreateAnimCursor
1243 0.9:
1244 AddTrapezoids
1245<