more shapes

1 files changed, 98 insertions, 53 deletions

diff --git a/docs/pixman shapes b/docs/pixman shapes
index 7c0f97ba..3d8c5d06 100644
--- a/docs/pixman shapes
+++ b/docs/pixman shapes
@@ -1,81 +1,126 @@
-- Spans
+There are several separate questions related to this:
 
-- In other cases we have had basically
+1. Can we support cairo's compositing operation better?
 
-	pixman_composite_shape (src, shape, dest, ...);
+2. Can we pass shape information to pixman more efficiently?
 
-  where shape could be triangles or trapezoids. In the glyphs
-  branch, I did something similar.
+and a tangential third one:
 
-- Is it correct that these two operator would be sufficient for
-  cairo to do most things in one pass:
+3. Should the pixman API be based on something other than images?
 
-bounded:
+-=-
 
-	(src OP dest) LERP_(shape IN clip) dest
+The first question pertains to the fact that cairo's operation is more
+complex than what pixman and X Render provides. This leads to extra
+work in cairo to construct the desired compositing operation.
 
-unbounded:
+One aspect of this is that cairo supports clipping to arbitrary
+shapes, whereas pixman only supports axis aligned regions. A
+straightforward fix for this is just add support for clip images:
 
-	((src IN shape) OP dest) LERP_clip dest
+        pixman_image_set_clip_image (
+		pixman_image_t *image, pixman_image_t *clip);
 
-If clip is a pixel-aligned, rectangular region, then these two
-operators degenerate to
+which means that when @image is used as a destination, all rendering
+is clipped to @clip in addition to being clipped to the clip
+region. (We need both the region and the clip image because the X
+server will want to set a clip region based on the window hierarchy in
+any case).
 
-	1. Set clip region on the destination
+The simplest way to implement this is to have the general
+implementation run an iterator for the clip image, and then pass a
+clip buffer to the combiners. In addition to computing the regular
+operator, the combiners would then also do LERP_clip onto the
+destination buffer.
 
-	2. bounded:     (src OP dest) LERP_shape dest
-	   unbounded:   (src IN shape) OP dest
+It may also be that it would more useful to add a new
 
-Unfortunately, cairo clips can be arbitrary shapes so this is not
-sufficient for cairo's needs. The shaped clips is a in cairo's
-API, but given the lack of a time machine, we can't fix that. But
-maybe the right solution is to add arbitrarily shaped clips to
-pixman:
+	pixman_image_composite_with_clip (src, mask, dest, clip, ...)
 
-    pixman_image_set_clip_image (
-	pixman_image_t *image, pixman_image_t *clip);
+function that takes a clip image in addition to src, mask, and
+dest.
 
-which would use the alpha channel (or all four channels in a
-per-component way?) of @clip as clip whenever image was used as a
-destination. It is fairly straight-forward to add this feature:
-the general implementation just has to deal with another
-iterator.
 
-It may also be that it's more useful to add a new 
+Another aspect is that cairo uses a different rendering equation in
+some cases. The two equations used are:
 
-	pixman_image_composite_with_cilp()
+     unbounded     [(src IN shape) OP dest		] LERP_clip dest
+
+     bounded       [(src OP dest) LERP_shape dest	] LERP_clip dest
+
+With shaped clips, the first equation is supported directly by pixman,
+and the second one could be supported by simply adding new <op>_LERP
+operators. For cairo's purposes, we would only need CLEAR_LERP and
+SRC_LERP, but I think it could be useful to have the full set of LERP
+operators.
+
+-=-
+
+The second question is whether there is a more efficient way to pass
+shape information to pixman than passing them as 8 bit alpha
+masks.
+
+A polygon image is a possibility, and the one I would prefer it allows
+more processing to happen in one pass, and because it is a more
+compact representation which is useful for the X protocol. There could
+be a method on such an image to generate a list of spans, so that
+cairo wouldn't need to maintain its own polygon rasterizer.
+
+But passing the information as spans is another possibility. If we add
+the support for clip images, the obvious way to add spans support
+would be through a spans image:
+
+     pixman_image_create_spans (const pixman_span_t *spans, int n_spans);
+
+that could be used both as the shape and as the clip. The initial
+implementation of such an image would be very simple: just implement
+an iterator that walks the list of spans, generating argb buffers.
+
+An appealing prospect here is a fast path that processes both shape
+and clip in one pass. If both span lists are known to be sorted in YX
+order, then they could be processed in one linear pass through both.
+
+-=-
+
+Finally, the more tangential question is whether pixman's API should
+be based on image objects in the future. They are not necessarily a
+good match for either cairo or X. I have some halfbaked ideas here:
+
+   http://cgit.freedesktop.org/~sandmann/pixman/tree/docs/new-api?h=docs
+
+inspired by Chris' old suggestion that pixman should behave more like
+a GPU.
+
+The gist of it is that instead of operating on image objects, there is
+just one pixman_context_t that has a bunch of properties that can be
+set. Once all the properties are set, the user is expected to call
+pixman_context_composite().
+
+There is also an api that allows bulk setting of properties so that an
+application can submit a list of commands and pixman would then carry
+them out, pretty much like a GPU would.
+
+It could be considered a generalization of the pixman_compositor_t
+idea from Chris' patch.
 
-function that takes a clip image in addition to src, mask, and
-dest.
 
-There is an issue regarding what to do with the existing
-region-clip API. Possibilities include treating the effective
-clip as the intersection of the region and the shape, or ignoring
-the region whenever a clip image is set.
+Comments on all three questions welcome.
 
-I believe this feature by itself would solve a bunch of problems
-for cairo. One remaining problem would be the bounded operators,
-SRC and CLEAR. To support those, a new set of 
 
-	CLEAR_LERP
-	SRC_LERP
-	...
+----
 
-operators could be added, that would behave according to this
-formula:
 
-	(src OP dest) LERP_mask dest
 
-Then finally, a separate question is how to pass shape
-information to pixman. A polygon image is one possibility, and
-the one I would prefer, but spans is definitely another.
+Then finally, a separate question is how to pass shape information to
+pixman. A polygon image is one possibility, and the one I would
+prefer, but spans is definitely another.
 
-In that case, and given that both the mask and the clip would be
-given as spans, it is tempting to pass them as images:
+In that case, and given that both the mask and the clip would be given
+as spans, it is tempting to pass them as images:
 
 	pixman_image_create_spans (pixman_span_t *spans, int n_spans)
 
 A first implementation could be totally trivial and just use a
-pixman_iter_t iterator to walk the spans. Later on fast paths
-could be added. Such fast paths could deal with both clipping and
-masking in one pass.
+pixman_iter_t iterator to walk the spans. Later on fast paths could be
+added. Such fast paths could deal with both clipping and masking in
+one pass.