summaryrefslogtreecommitdiff
path: root/renderproto.txt
diff options
context:
space:
mode:
authorSøren Sandmann Pedersen <sandmann@redhat.com>2009-05-01 19:39:47 -0400
committerSøren Sandmann Pedersen <sandmann@redhat.com>2009-05-01 20:44:03 -0400
commitc4315b2a4704c88924e7a6bc444b5331caa64022 (patch)
tree501d466832c4286188f3fdfeedb08cd5fad3d487 /renderproto.txt
parent2428785895f352f15fb412a630289e44bb2e7cc3 (diff)
Clarify semantics of clipping
Source clips are applied on top of the transformed and repeated window, because that way you can clip out an interesting shape of for example a repeated gradient, and because this makes the implementation simple and efficient. GraphicsExposures are never generated. The hierarchy clip is ignored for source and mask pictures. This is because GraphicsExposures are not generated anyway, and because implementing it correctly in the presense of filters and transformations would be either inefficient or very complex. Also make it explicit that the dither argument is not used.
Diffstat (limited to 'renderproto.txt')
-rw-r--r--renderproto.txt73
1 files changed, 34 insertions, 39 deletions
diff --git a/renderproto.txt b/renderproto.txt
index ef371b9..438ce16 100644
--- a/renderproto.txt
+++ b/renderproto.txt
@@ -607,70 +607,63 @@ CreatePicture
dither: ATOM or None
component-alpha: BOOL
- When used as a source or mask operand, the repeat and fill-constant
- values control how pixels outside the geometry of the drawable are
- computed.
-
- Repeat indicates how the drawable contents should be extented
- in both directions.
+ When used as a source or mask operand, 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
alpha-mask origin is interpreted relative to the origin of drawable.
- Rendering is additionally clipped by the geometry of alpha-map.
- Exposures to the window do not affect the contents of alpha-map.
- Alpha-map must refer to a picture containing a Pixmap, not a Window
- (or a Match error results).
+ Rendering is additionally clipped by the geometry and clip mask of
+ alpha-map. Exposures to the window do not affect the contents of
+ alpha-map. Alpha-map must refer to a picture containing a Pixmap,
+ not a Window (or a Match error results).
The clip-mask restricts reads and writes to drawable. Only pixels
where the clip-mask has bits set to 1 are read or written. Pixels
are not accessed outside the area covered by the clip-mask or where
the clip-mask has bits set to 0. The clip-mask affects all graphics
requests, including sources. The clip-mask origin is interpreted
- relative to the origin of drawable. If a pixmap is specified as the
- clip-mask, it must have depth 1 and have the same root as the
+ relative to the origin of the picture. If a pixmap is specified as
+ the clip-mask, it must have depth 1 and have the same root as the
drawable (or a Match error results). If clip-mask is None, then
pixels are always drawn, regardless of the clip origin. The
clip-mask can also be set with the SetPictureClipRectangles request.
-
- For ClipByChildren, both source and destination windows are
- additionally clipped by all viewable InputOutput children. For
- IncludeInferiors , neither source nor destination window is clipped
- by inferiors. This will result in including subwindow contents in
- the source and drawing through subwindow boundaries of the
- destination. The use of IncludeInferiors with a source or
+ Transformations, filters and repeat modes do not affect the clip
+ mask.
+
+ For ClipByChildren, destination - but not source - windows are
+ additionally clipped by all viewable InputOutput children.
+
+ For IncludeInferiors, neither source nor destination windows are
+ clipped by inferiors. This will result in including subwindow
+ contents in the source and drawing through subwindow boundaries of
+ the destination. The use of IncludeInferiors with a source or
destination window of one depth with mapped inferiors of differing
depth is not illegal, but the semantics are undefined by this
extension.
- The graphics-exposures flag controls GraphicsExposure event
- generation for Composite requests (and any similar requests
- defined by additional extensions).
+ The graphics-exposures flag is ignored. GraphicsExposure events are
+ never generated by this extension.
- Poly-edge and poly-mode control the rasterization of polygons
- as described above.
+ Poly-edge and poly-mode control the rasterization of polygons as
+ described above.
- Dither selects which of the available dither patterns should
- be used. If dither is None, no dithering will be done.
+ Dither is ignored.
- Component-alpha indicates whether each image component is
- intended as a separate alpha value when the picture is used
- as a mask operand.
+ Component-alpha indicates whether each image component is intended as
+ a separate alpha value when the picture is used as a mask operand.
The default component values are
Component Default
-------------------------------
- repeat False
- fill-nearest: False
+ repeat None
clip-x-origin 0
clip-y-origin 0
clip-mask None
- graphics-exposures True
subwindow-mode ClipByChildren
poly-edge Smooth
poly-mode Precise
- dither None
component-alpha False
ChangePicture
@@ -699,12 +692,14 @@ SetPictureClipRectangles
This request changes clip-mask in picture to the specified list of
rectangles and sets the clip origin. Input and output will be
clipped to remain contained within the rectangles. The clip origin
- is interpreted relative to the origin of the drawable associated
- with picture. The rectangle coordinates are interpreted relative to
- the clip origin. Note that the list of rectangles can be empty,
- which effectively disables output. This is the opposite of passing
- None as the clip-mask in CreatePicture and ChangePicture.
-
+ is interpreted relative to the origin of picture after
+ transformations and repeats have been applied. The rectangle
+ coordinates are interpreted relative to the clip origin.
+
+ The list of rectangles can be empty, which effectively disables
+ output. This is the opposite of passing None as the clip-mask in
+ CreatePicture and ChangePicture.
+
Note that output is clipped to the union of all of the rectangles
and that no particular ordering among the rectangles is required.