[cairo] CAIRO_OPERATOR_SOURCE not handled by backend

[Carl Worth]

On Tue, 20 Mar 2007 19:18:13 +0100, "Sebastian Tusk" wrote:
> > XRender can not. I am not sure about the other backends, though I think
> > Quartz (at least newer ones) might be able to do it more efficiently.
>
> Is this an API limitation?

The Render interface was defined with the following compositing
equation:

	destination' = (source IN mask) OP destination

and also defined to act only within a rectangle, (either explicit in
the case of Composite or implicitly in the case of CompositeTrapezoids
where Render uses the bounding box of the trapezoids).

If you plug SOURCE in as OP in the above equation, the result is
effectively copying the source to the destination "inside" the mask,
and zeroing out the destination everywhere "outside" the mask, but
inside the appropriate rectangle.

That turns out to be a rather unuseful result, particularly in the
case of CompositeTrapezoids. If cairo sets up a list of trapezoids
representing some filled path, and passes those directly to Render's
CompositeTrapezoids call, the result is a big, ugly black box that
appears around the bounds of the trapezoid.

When developing cairo, we wrote code that did exactly that, and saw
that big, ugly box. It's obviously not useful for anything,
(basically, no cairo rendering of a path should have any effect that
makes the bounding box appear). So we went through the effort to
decide what would be useful instead.

One option would have been to allow the zeroing out of the destination
to occur everywhere "outside" of the mask.

But even that wasn't satisfying as a useful thing for cairo to
provide. We asked the question: If a user specifies the SOURCE
operator and asks to fill a path, what should the user expect to get?
The answer we came up with is that the user should get the result of
doing (source SOURCE dest) but restricted to operate within the mask.

For all the gory details that led to this, we can thank Owen Taylor
for providing a lot of insight, a bunch of careful math and
experimentation and some useful writeups (this all took place just
before the cairo 1.0 release which froze the currently implemented
semantics):

	Details of revised rendering equation
	http://lists.freedesktop.org/archives/cairo/2005-August/004718.html

	Redoing SOURCE and CLEAR
	http://article.gmane.org/gmane.comp.lib.cairo/4791

The first details how we took Render's equation above and extended it
to handle cairo's notion of clipping. The second details the change we
made to SOURCE and CLEAR so that they operate only within the mask and
not outside of it.

So the messages above, (along with others in the threads), contain
most the information that really needs to be extracted out to form the
introductory chapter of a document describing cairo's imaging model.

Meanwhile, a lot of the internals of cairo, (including the surface
backend interface), still retain a lot of the original Render heritage
from which they were originally based. So the complex code you see in
_clip_and_composite is the strategy for implementing the "new" cairo
semantics on top of the "old" Render semantics.

And as Jeff described, what would be much nicer to have internally
would be something that tried to execute cairo's semantics through the
backend, and only fell back to the current workarounds if the backend
couldn't deal with it. This might allow your backend, (what is it, by
the way?), to be implemented more efficiently. It might also allow for
a future revision of the Render specification which would allow cairo
to use a more efficient implementation.

I hope that helps explain things,

-Carl

PS. For reference, here are the final equations that Owen proposed in
the second message linked to above, (and I believe these are the final
semantics adopted into cairo 1.0 and all subsequent releases and
codified in cairo's test suite):

On 2005-08-17, at 15:45:19 GMT Owen Taylor wrote:
>
> So, the proposal here is to logically divide the operators into
> 4 groups by what definition we use:
>
>  OVER, ATOP, DEST, DEST_OVER, DEST_OUT, XOR, ADD
>
>    All definitions equivalent
>
>  SOURCE, CLEAR
>
>    (mask IN clip) ? src OP dest : dest
>
>  IN, OUT, DEST_IN, DEST_ATOP
>
>    clip ? (src IN mask) OP dest : dest
>
>  SATURATE
>
>    (src IN mask IN clip) OP dest
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20070320/2ce2921e/attachment.pgp